crypto/heimdal/lib/krb5/krb5_ccache.3

   1 .\" Copyright (c) 2003 - 2005 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: krb5_ccache.3 22071 2007-11-14 20:04:50Z lha $
  33 .\"
  34 .Dd October 19, 2005
  35 .Dt KRB5_CCACHE 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_ccache ,
  39 .Nm krb5_cc_cursor ,
  40 .Nm krb5_cc_ops ,
  41 .Nm krb5_fcc_ops ,
  42 .Nm krb5_mcc_ops ,
  43 .Nm krb5_cc_clear_mcred ,
  44 .Nm krb5_cc_close ,
  45 .Nm krb5_cc_copy_cache ,
  46 .Nm krb5_cc_default ,
  47 .Nm krb5_cc_default_name ,
  48 .Nm krb5_cc_destroy ,
  49 .Nm krb5_cc_end_seq_get ,
  50 .Nm krb5_cc_gen_new ,
  51 .Nm krb5_cc_get_full_name ,
  52 .Nm krb5_cc_get_name ,
  53 .Nm krb5_cc_get_ops ,
  54 .Nm krb5_cc_get_prefix_ops ,
  55 .Nm krb5_cc_get_principal ,
  56 .Nm krb5_cc_get_type ,
  57 .Nm krb5_cc_get_version ,
  58 .Nm krb5_cc_initialize ,
  59 .Nm krb5_cc_next_cred ,
  60 .Nm krb5_cc_next_cred_match ,
  61 .Nm krb5_cc_new_unique ,
  62 .Nm krb5_cc_register ,
  63 .Nm krb5_cc_remove_cred ,
  64 .Nm krb5_cc_resolve ,
  65 .Nm krb5_cc_retrieve_cred ,
  66 .Nm krb5_cc_set_default_name ,
  67 .Nm krb5_cc_set_flags ,
  68 .Nm krb5_cc_start_seq_get ,
  69 .Nm krb5_cc_store_cred
  70 .Nd mange credential cache
  71 .Sh LIBRARY
  72 Kerberos 5 Library (libkrb5, -lkrb5)
  73 .Sh SYNOPSIS
  74 .In krb5.h
  75 .Pp
  76 .Li "struct krb5_ccache;"
  77 .Pp
  78 .Li "struct krb5_cc_cursor;"
  79 .Pp
  80 .Li "struct krb5_cc_ops;"
  81 .Pp
  82 .Li "struct krb5_cc_ops *krb5_fcc_ops;"
  83 .Pp
  84 .Li "struct krb5_cc_ops *krb5_mcc_ops;"
  85 .Pp
  86 .Ft void
  87 .Fo krb5_cc_clear_mcred
  88 .Fa "krb5_creds *mcred"
  89 .Fc
  90 .Ft krb5_error_code
  91 .Fo krb5_cc_close
  92 .Fa "krb5_context context"
  93 .Fa "krb5_ccache id"
  94 .Fc
  95 .Ft krb5_error_code
  96 .Fo krb5_cc_copy_cache
  97 .Fa "krb5_context context"
  98 .Fa "const krb5_ccache from"
  99 .Fa "krb5_ccache to"
 100 .Fc
 101 .Ft krb5_error_code
 102 .Fo krb5_cc_default
 103 .Fa "krb5_context context"
 104 .Fa "krb5_ccache *id"
 105 .Fc
 106 .Ft "const char *"
 107 .Fo krb5_cc_default_name
 108 .Fa "krb5_context context"
 109 .Fc
 110 .Ft krb5_error_code
 111 .Fo krb5_cc_destroy
 112 .Fa "krb5_context context"
 113 .Fa "krb5_ccache id"
 114 .Fc
 115 .Ft krb5_error_code
 116 .Fo krb5_cc_end_seq_get
 117 .Fa "krb5_context context"
 118 .Fa "const krb5_ccache id"
 119 .Fa "krb5_cc_cursor *cursor"
 120 .Fc
 121 .Ft krb5_error_code
 122 .Fo krb5_cc_gen_new
 123 .Fa "krb5_context context"
 124 .Fa "const krb5_cc_ops *ops"
 125 .Fa "krb5_ccache *id"
 126 .Fc
 127 .Ft krb5_error_code
 128 .Fo krb5_cc_get_full_name
 129 .Fa "krb5_context context"
 130 .Fa "krb5_ccache id"
 131 .Fa "char **str"
 132 .Fc
 133 .Ft "const char *"
 134 .Fo krb5_cc_get_name
 135 .Fa "krb5_context context"
 136 .Fa "krb5_ccache id"
 137 .Fc
 138 .Ft krb5_error_code
 139 .Fo krb5_cc_get_principal
 140 .Fa "krb5_context context"
 141 .Fa "krb5_ccache id"
 142 .Fa "krb5_principal *principal"
 143 .Fc
 144 .Ft "const char *"
 145 .Fo krb5_cc_get_type
 146 .Fa "krb5_context context"
 147 .Fa "krb5_ccache id"
 148 .Fc
 149 .Ft "const krb5_cc_ops *"
 150 .Fo krb5_cc_get_ops
 151 .Fa "krb5_context context"
 152 .Fa "krb5_ccache id"
 153 .Fc
 154 .Ft "const krb5_cc_ops *"
 155 .Fo krb5_cc_get_prefix_ops
 156 .Fa "krb5_context context"
 157 .Fa "const char *prefix"
 158 .Fc
 159 .Ft krb5_error_code
 160 .Fo krb5_cc_get_version
 161 .Fa "krb5_context context"
 162 .Fa "const krb5_ccache id"
 163 .Fc
 164 .Ft krb5_error_code
 165 .Fo krb5_cc_initialize
 166 .Fa "krb5_context context"
 167 .Fa "krb5_ccache id"
 168 .Fa "krb5_principal primary_principal"
 169 .Fc
 170 .Ft krb5_error_code
 171 .Fo krb5_cc_register
 172 .Fa "krb5_context context"
 173 .Fa "const krb5_cc_ops *ops"
 174 .Fa "krb5_boolean override"
 175 .Fc
 176 .Ft krb5_error_code
 177 .Fo krb5_cc_resolve
 178 .Fa "krb5_context context"
 179 .Fa "const char *name"
 180 .Fa "krb5_ccache *id"
 181 .Fc
 182 .Ft krb5_error_code
 183 .Fo krb5_cc_retrieve_cred
 184 .Fa "krb5_context context"
 185 .Fa "krb5_ccache id"
 186 .Fa "krb5_flags whichfields"
 187 .Fa "const krb5_creds *mcreds"
 188 .Fa "krb5_creds *creds"
 189 .Fc
 190 .Ft krb5_error_code
 191 .Fo krb5_cc_remove_cred
 192 .Fa "krb5_context context"
 193 .Fa "krb5_ccache id"
 194 .Fa "krb5_flags which"
 195 .Fa "krb5_creds *cred"
 196 .Fc
 197 .Ft krb5_error_code
 198 .Fo krb5_cc_set_default_name
 199 .Fa "krb5_context context"
 200 .Fa "const char *name"
 201 .Fc
 202 .Ft krb5_error_code
 203 .Fo krb5_cc_start_seq_get
 204 .Fa "krb5_context context"
 205 .Fa "const krb5_ccache id"
 206 .Fa "krb5_cc_cursor *cursor"
 207 .Fc
 208 .Ft krb5_error_code
 209 .Fo krb5_cc_store_cred
 210 .Fa "krb5_context context"
 211 .Fa "krb5_ccache id"
 212 .Fa "krb5_creds *creds"
 213 .Fc
 214 .Ft krb5_error_code
 215 .Fo krb5_cc_set_flags
 216 .Fa "krb5_context context"
 217 .Fa "krb5_cc_set_flags id"
 218 .Fa "krb5_flags flags"
 219 .Fc
 220 .Ft krb5_error_code
 221 .Fo krb5_cc_next_cred
 222 .Fa "krb5_context context"
 223 .Fa "const krb5_ccache id"
 224 .Fa "krb5_cc_cursor *cursor"
 225 .Fa "krb5_creds *creds"
 226 .Fc
 227 .Ft krb5_error_code
 228 .Fo krb5_cc_next_cred_match
 229 .Fa "krb5_context context"
 230 .Fa "const krb5_ccache id"
 231 .Fa "krb5_cc_cursor *cursor"
 232 .Fa "krb5_creds *creds"
 233 .Fa "krb5_flags whichfields"
 234 .Fa "const krb5_creds *mcreds"
 235 .Fc
 236 .Ft krb5_error_code
 237 .Fo krb5_cc_new_unique
 238 .Fa "krb5_context context"
 239 .Fa "const char *type"
 240 .Fa "const char *hint"
 241 .Fa "krb5_ccache *id"
 242 .Fc
 243 .Sh DESCRIPTION
 244 The
 245 .Li krb5_ccache
 246 structure holds a Kerberos credential cache.
 247 .Pp
 248 The
 249 .Li krb5_cc_cursor
 250 structure holds current position in a credential cache when
 251 iterating over the cache.
 252 .Pp
 253 The
 254 .Li krb5_cc_ops
 255 structure holds a set of operations that can me preformed on a
 256 credential cache.
 257 .Pp
 258 There is no component inside
 259 .Li krb5_ccache ,
 260 .Li krb5_cc_cursor
 261 nor
 262 .Li krb5_fcc_ops
 263 that is directly referable.
 264 .Pp
 265 The
 266 .Li krb5_creds
 267 holds a Kerberos credential, see manpage for
 268 .Xr krb5_creds 3 .
 269 .Pp
 270 .Fn krb5_cc_default_name
 271 and
 272 .Fn krb5_cc_set_default_name
 273 gets and sets the default name for the
 274 .Fa context .
 275 .Pp
 276 .Fn krb5_cc_default
 277 opens the default credential cache in
 278 .Fa id .
 279 Return 0 or an error code.
 280 .Pp
 281 .Fn krb5_cc_gen_new
 282 generates a new credential cache of type
 283 .Fa ops
 284 in
 285 .Fa id .
 286 Return 0 or an error code.
 287 The Heimdal version of this function also runs
 288 .Fn krb5_cc_initialize
 289 on the credential cache, but since the MIT version doesn't, portable
 290 code must call krb5_cc_initialize.
 291 .Pp
 292 .Fn krb5_cc_new_unique
 293 generates a new unique credential cache of
 294 .Fa type
 295 in
 296 .Fa id .
 297 If type is
 298 .Dv NULL ,
 299 the library chooses the default credential cache type.
 300 The supplied
 301 .Fa hint
 302 (that can be
 303 .Dv NULL )
 304 is a string that the credential cache type can use to base the name of
 305 the credential on, this is to make it easier for the user to
 306 differentiate the credentials.
 307 The returned credential cache
 308 .Fa id
 309 should be freed using
 310 .Fn krb5_cc_close
 311 or
 312 .Fn krb5_cc_destroy .
 313 Returns 0 or an error code.
 314 .Pp
 315 .Fn krb5_cc_resolve
 316 finds and allocates a credential cache in
 317 .Fa id
 318 from the specification in
 319 .Fa residual .
 320 If the credential cache name doesn't contain any colon (:), interpret it as a
 321 file name.
 322 Return 0 or an error code.
 323 .Pp
 324 .Fn krb5_cc_initialize
 325 creates a new credential cache in
 326 .Fa id
 327 for
 328 .Fa primary_principal .
 329 Return 0 or an error code.
 330 .Pp
 331 .Fn krb5_cc_close
 332 stops using the credential cache
 333 .Fa id
 334 and frees the related resources.
 335 Return 0 or an error code.
 336 .Fn krb5_cc_destroy
 337 removes the credential cache
 338 and closes (by calling
 339 .Fn krb5_cc_close )
 340 .Fa id .
 341 Return 0 or an error code.
 342 .Pp
 343 .Fn krb5_cc_copy_cache
 344 copys the contents of
 345 .Fa from
 346 to
 347 .Fa to .
 348 .Pp
 349 .Fn krb5_cc_get_full_name
 350 returns the complete resolvable name of the credential cache
 351 .Fa id
 352 in
 353 .Fa str .
 354 .Fa str
 355 should be freed with
 356 .Xr free 3 .
 357 Returns 0 or an error, on error
 358 .Fa *str
 359 is set to
 360 .Dv NULL .
 361 .Pp
 362 .Fn krb5_cc_get_name
 363 returns the name of the credential cache
 364 .Fa id .
 365 .Pp
 366 .Fn krb5_cc_get_principal
 367 returns the principal of
 368 .Fa id
 369 in
 370 .Fa principal .
 371 Return 0 or an error code.
 372 .Pp
 373 .Fn krb5_cc_get_type
 374 returns the type of the credential cache
 375 .Fa id .
 376 .Pp
 377 .Fn krb5_cc_get_ops
 378 returns the ops of the credential cache
 379 .Fa id .
 380 .Pp
 381 .Fn krb5_cc_get_version
 382 returns the version of
 383 .Fa id .
 384 .Pp
 385 .Fn krb5_cc_register
 386 Adds a new credential cache type with operations
 387 .Fa ops ,
 388 overwriting any existing one if
 389 .Fa override .
 390 Return an error code or 0.
 391 .Pp
 392 .Fn krb5_cc_get_prefix_ops
 393 Get the cc ops that is registered in
 394 .Fa context
 395 to handle the
 396 .Fa prefix .
 397 Returns
 398 .Dv NULL
 399 if ops not found.
 400 .Pp
 401 .Fn krb5_cc_remove_cred
 402 removes the credential identified by
 403 .Fa ( cred ,
 404 .Fa which )
 405 from
 406 .Fa id .
 407 .Pp
 408 .Fn krb5_cc_store_cred
 409 stores
 410 .Fa creds
 411 in the credential cache
 412 .Fa id .
 413 Return 0 or an error code.
 414 .Pp
 415 .Fn krb5_cc_set_flags
 416 sets the flags of
 417 .Fa id
 418 to
 419 .Fa flags .
 420 .Pp
 421 .Fn krb5_cc_clear_mcred
 422 clears the
 423 .Fa mcreds
 424 argument so it is reset and can be used with
 425 .Fa krb5_cc_retrieve_cred .
 426 .Pp
 427 .Fn krb5_cc_retrieve_cred ,
 428 retrieves the credential identified by
 429 .Fa mcreds
 430 (and
 431 .Fa whichfields )
 432 from
 433 .Fa id
 434 in
 435 .Fa creds .
 436 .Fa creds
 437 should be freed using
 438 .Fn krb5_free_cred_contents .
 439 Return 0 or an error code.
 440 .Pp
 441 .Fn krb5_cc_start_seq_get
 442 initiates the
 443 .Li krb5_cc_cursor
 444 structure to be used for iteration over the credential cache.
 445 .Pp
 446 .Fn krb5_cc_next_cred
 447 retrieves the next cred pointed to by
 448 .Fa ( id ,
 449 .Fa cursor )
 450 in
 451 .Fa creds ,
 452 and advance
 453 .Fa cursor .
 454 Return 0 or an error code.
 455 .Pp
 456 .Fn krb5_cc_next_cred_match
 457 is similar to
 458 .Fn krb5_cc_next_cred
 459 except that it will only return creds matching
 460 .Fa whichfields
 461 and
 462 .Fa mcreds
 463 (as interpreted by
 464 .Xr krb5_compare_creds 3 . )
 465 .Pp
 466 .Fn krb5_cc_end_seq_get
 467 Destroys the cursor
 468 .Fa cursor .
 469 .Sh EXAMPLE
 470 This is a minimalistic version of
 471 .Nm klist .
 472 .Pp
 473 .Bd -literal
 474 #include <krb5.h>
 475
 476 int
 477 main (int argc, char **argv)
 478 {
 479     krb5_context context;
 480     krb5_cc_cursor cursor;
 481     krb5_error_code ret;
 482     krb5_ccache id;
 483     krb5_creds creds;
 484
 485     if (krb5_init_context (&context) != 0)
 486         errx(1, "krb5_context");
 487
 488     ret = krb5_cc_default (context, &id);
 489     if (ret)
 490         krb5_err(context, 1, ret, "krb5_cc_default");
 491
 492     ret = krb5_cc_start_seq_get(context, id, &cursor);
 493     if (ret)
 494         krb5_err(context, 1, ret, "krb5_cc_start_seq_get");
 495
 496     while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){
 497         char *principal;
 498
 499         krb5_unparse_name_short(context, creds.server, &principal);
 500         printf("principal: %s\\n", principal);
 501         free(principal);
 502         krb5_free_cred_contents (context, &creds);
 503     }
 504     ret = krb5_cc_end_seq_get(context, id, &cursor);
 505     if (ret)
 506         krb5_err(context, 1, ret, "krb5_cc_end_seq_get");
 507
 508     krb5_cc_close(context, id);
 509
 510     krb5_free_context(context);
 511     return 0;
 512 }
 513 .Ed
 514 .Sh SEE ALSO
 515 .Xr krb5 3 ,
 516 .Xr krb5.conf 5 ,
 517 .Xr kerberos 8