crypto/heimdal-0.6.3/lib/krb5/krb5_ccache.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: krb5_ccache.3,v 1.7 2003/04/16 13:58:12 lha Exp $
  33 .\"
  34 .Dd March 16, 2003
  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_close ,
  44 .Nm krb5_cc_copy_cache ,
  45 .Nm krb5_cc_default ,
  46 .Nm krb5_cc_default_name ,
  47 .Nm krb5_cc_destroy ,
  48 .Nm krb5_cc_end_seq_get ,
  49 .Nm krb5_cc_gen_new ,
  50 .Nm krb5_cc_get_name ,
  51 .Nm krb5_cc_get_principal ,
  52 .Nm krb5_cc_get_type ,
  53 .Nm krb5_cc_get_ops ,
  54 .Nm krb5_cc_get_version ,
  55 .Nm krb5_cc_initialize ,
  56 .Nm krb5_cc_register ,
  57 .Nm krb5_cc_resolve ,
  58 .Nm krb5_cc_retrieve_cred ,
  59 .Nm krb5_cc_remove_cred ,
  60 .Nm krb5_cc_set_default_name ,
  61 .Nm krb5_cc_store_cred ,
  62 .Nm krb5_cc_set_flags ,
  63 .Nm krb5_cc_next_cred
  64 .Nd mange credential cache.
  65 .Sh LIBRARY
  66 Kerberos 5 Library (libkrb5, -lkrb5)
  67 .Sh SYNOPSIS
  68 .In krb5.h
  69 .Pp
  70 .Li "struct krb5_ccache;"
  71 .Pp
  72 .Li "struct krb5_cc_cursor;"
  73 .Pp
  74 .Li "struct krb5_cc_ops;"
  75 .Pp
  76 .Li "struct krb5_cc_ops *krb5_fcc_ops;"
  77 .Pp
  78 .Li "struct krb5_cc_ops *krb5_mcc_ops;"
  79 .Pp
  80 .Ft krb5_error_code
  81 .Fo krb5_cc_close
  82 .Fa "krb5_context *context"
  83 .Fa "krb5_ccache id"
  84 .Fc
  85 .Ft krb5_error_code
  86 .Fo krb5_cc_copy_cache
  87 .Fa "krb5_context *context"
  88 .Fa "const krb5_ccache from"
  89 .Fa "krb5_ccache to"
  90 .Fc
  91 .Ft krb5_error_code
  92 .Fo krb5_cc_default
  93 .Fa "krb5_context *context"
  94 .Fa "krb5_ccache *id"
  95 .Fc
  96 .Ft "const char *"
  97 .Fo krb5_cc_default_name
  98 .Fa "krb5_context *context"
  99 .Fc
 100 .Ft krb5_error_code
 101 .Fo krb5_cc_destroy
 102 .Fa "krb5_context *context"
 103 .Fa "krb5_ccache id"
 104 .Fc
 105 .Ft krb5_error_code
 106 .Fo krb5_cc_end_seq_get
 107 .Fa "krb5_context *context"
 108 .Fa "const krb5_ccache id"
 109 .Fa "krb5_cc_cursor *cursor"
 110 .Fc
 111 .Ft krb5_error_code
 112 .Fo krb5_cc_gen_new
 113 .Fa "krb5_context *context"
 114 .Fa "const krb5_cc_ops *ops"
 115 .Fa "krb5_ccache *id"
 116 .Fc
 117 .Ft "const char *"
 118 .Fo krb5_cc_get_name
 119 .Fa "krb5_context *context"
 120 .Fa "krb5_ccache id"
 121 .Fc
 122 .Ft krb5_error_code
 123 .Fo krb5_cc_get_principal
 124 .Fa "krb5_context *context"
 125 .Fa "krb5_ccache id"
 126 .Fa "krb5_principal *principal"
 127 .Fc
 128 .Ft "const char *"
 129 .Fo krb5_cc_get_type
 130 .Fa "krb5_context *context"
 131 .Fa "krb5_ccache id"
 132 .Fc
 133 .Ft "const krb5_cc_ops *"
 134 .Fo krb5_cc_get_ops
 135 .Fa "krb5_context *context"
 136 .Fa "krb5_ccache id"
 137 .Fc
 138 .Ft krb5_error_code
 139 .Fo krb5_cc_get_version
 140 .Fa "krb5_context *context"
 141 .Fa "const krb5_ccache id"
 142 .Fc
 143 .Ft krb5_error_code
 144 .Fo krb5_cc_initialize
 145 .Fa "krb5_context *context"
 146 .Fa "krb5_ccache id"
 147 .Fa "krb5_principal primary_principal"
 148 .Fc
 149 .Ft krb5_error_code
 150 .Fo krb5_cc_register
 151 .Fa "krb5_context *context"
 152 .Fa "const krb5_cc_ops *ops"
 153 .Fa "krb5_boolean override"
 154 .Fc
 155 .Ft krb5_error_code
 156 .Fo krb5_cc_resolve
 157 .Fa "krb5_context *context"
 158 .Fa "const char *name"
 159 .Fa "krb5_ccache *id"
 160 .Fc
 161 .Ft krb5_error_code
 162 .Fo krb5_cc_retrieve_cred
 163 .Fa "krb5_context *context"
 164 .Fa "krb5_ccache id"
 165 .Fa "krb5_flags whichfields"
 166 .Fa "const krb5_creds *mcreds"
 167 .Fa "krb5_creds *creds"
 168 .Fc
 169 .Ft krb5_error_code
 170 .Fo krb5_cc_remove_cred
 171 .Fa "krb5_context *context"
 172 .Fa "krb5_ccache id"
 173 .Fa "krb5_flags which"
 174 .Fa "krb5_creds *cred"
 175 .Fc
 176 .Ft krb5_error_code
 177 .Fo krb5_cc_set_default_name
 178 .Fa "krb5_context *context"
 179 .Fa "const char *name"
 180 .Fc
 181 .Ft krb5_error_code
 182 .Fo krb5_cc_store_cred
 183 .Fa "krb5_context *context"
 184 .Fa "krb5_ccache id"
 185 .Fa "krb5_creds *creds"
 186 .Fc
 187 .Ft krb5_error_code
 188 .Fo krb5_cc_set_flags
 189 .Fa "krb5_context *context"
 190 .Fa "krb5_cc_set_flags id"
 191 .Fa "krb5_flags flags"
 192 .Fc
 193 .Ft krb5_error_code
 194 .Fo krb5_cc_next_cred
 195 .Fa "krb5_context *context"
 196 .Fa "const krb5_ccache id"
 197 .Fa "krb5_cc_cursor *cursor"
 198 .Fa "krb5_creds *creds"
 199 .Fc
 200 .Sh DESCRIPTION
 201 The
 202 .Li krb5_ccache
 203 structure holds a Kerberos credential cache.
 204 .Pp
 205 The
 206 .Li krb5_cc_cursor
 207 structure holds current position in a credential cache when
 208 iterating over the cache.
 209 .Pp
 210 The
 211 .Li krb5_cc_ops
 212 structure holds a set of operations that can me preformed on a
 213 credential cache.
 214 .Pp
 215 There is no component inside
 216 .Li krb5_ccache ,
 217 .Li krb5_cc_cursor
 218 nor
 219 .Li krb5_fcc_ops
 220 that is directly referable.
 221 .Pp
 222 The
 223 .Li krb5_creds
 224 holds a Kerberos credential, see manpage for
 225 .Xr krb5_creds 3 .
 226 .Pp
 227 .Fn krb5_cc_default_name
 228 and
 229 .Fn krb5_cc_set_default_name
 230 gets and sets the default name for the
 231 .Fa context .
 232 .Pp
 233 .Fn krb5_cc_default
 234 opens the default ccache in
 235 .Fa id .
 236 Return 0 or an error code.
 237 .Pp
 238 .Fn krb5_cc_gen_new
 239 generates a new ccache of type
 240 .Fa ops
 241 in
 242 .Fa id .
 243 Return 0 or an error code.
 244 .Pp
 245 .Fn krb5_cc_resolve
 246 finds and allocates a ccache in
 247 .Fa id
 248 from the specification in
 249 .Fa residual .
 250 If the ccache name doesn't contain any colon (:), interpret it as a
 251 file name.
 252 Return 0 or an error code.
 253 .Pp
 254 .Fn krb5_cc_initialize
 255 creates a new ccache in
 256 .Fa id
 257 for
 258 .Fa primary_principal .
 259 Return 0 or an error code.
 260 .Pp
 261 .Fn krb5_cc_close
 262 stops using the ccache
 263 .Fa id
 264 and frees the related resources.
 265 Return 0 or an error code.
 266 .Fn krb5_cc_destroy
 267 removes the ccache
 268 and closes (by calling
 269 .Fn krb5_cc_close )
 270 .Fa id .
 271 Return 0 or an error code.
 272 .Pp
 273 .Fn krb5_cc_copy_cache
 274 copys the contents of
 275 .Fa from
 276 to
 277 .Fa to .
 278 .Pp
 279 .Fn krb5_cc_get_name
 280 returns the name of the ccache
 281 .Fa id .
 282 .Pp
 283 .Fn krb5_cc_get_principal
 284 returns the principal of
 285 .Fa id
 286 in
 287 .Fa principal .
 288 Return 0 or an error code.
 289 .Pp
 290 .Fn krb5_cc_get_type
 291 returns the type of the ccache
 292 .Fa id .
 293 .Pp
 294 .Fn krb5_cc_get_ops
 295 returns the ops of the ccache
 296 .Fa id .
 297 .Pp
 298 .Fn krb5_cc_get_version
 299 returns the version of
 300 .Fa id .
 301 .Pp
 302 .Fn krb5_cc_register
 303 Adds a new ccache type with operations
 304 .Fa ops ,
 305 overwriting any existing one if
 306 .Fa override .
 307 Return an error code or 0.
 308 .Pp
 309 .Fn krb5_cc_remove_cred
 310 removes the credential identified by
 311 .Fa ( cred ,
 312 .Fa which )
 313 from
 314 .Fa id .
 315 .Pp
 316 .Fn krb5_cc_store_cred
 317 stores
 318 .Fa creds
 319 in the ccache
 320 .Fa id .
 321 Return 0 or an error code.
 322 .Pp
 323 .Fn krb5_cc_set_flags
 324 sets the flags of
 325 .Fa id
 326 to
 327 .Fa flags .
 328 .Pp
 329 .Fn krb5_cc_retrieve_cred ,
 330 retrieves the credential identified by
 331 .Fa mcreds
 332 (and
 333 .Fa whichfields )
 334 from
 335 .Fa id
 336 in
 337 .Fa creds .
 338 Return 0 or an error code.
 339 .Pp
 340 .Fn krb5_cc_next_cred
 341 retrieves the next cred pointed to by
 342 .Fa ( id ,
 343 .Fa cursor )
 344 in
 345 .Fa creds ,
 346 and advance
 347 .Fa cursor .
 348 Return 0 or an error code.
 349 .Pp
 350 .Fn krb5_cc_end_seq_get
 351 Destroys the cursor
 352 .Fa cursor .
 353 .Sh SEE ALSO
 354 .Xr krb5 3 ,
 355 .Xr krb5.conf 5 ,
 356 .Xr kerberos 8