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