crypto/heimdal/lib/krb5/krb5_keytab.3

   1 .\" Copyright (c) 2001 - 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_keytab.3 22071 2007-11-14 20:04:50Z lha $
  33 .\"
  34 .Dd August 12, 2005
  35 .Dt KRB5_KEYTAB 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_kt_ops ,
  39 .Nm krb5_keytab_entry ,
  40 .Nm krb5_kt_cursor ,
  41 .Nm krb5_kt_add_entry ,
  42 .Nm krb5_kt_close ,
  43 .Nm krb5_kt_compare ,
  44 .Nm krb5_kt_copy_entry_contents ,
  45 .Nm krb5_kt_default ,
  46 .Nm krb5_kt_default_modify_name ,
  47 .Nm krb5_kt_default_name ,
  48 .Nm krb5_kt_end_seq_get ,
  49 .Nm krb5_kt_free_entry ,
  50 .Nm krb5_kt_get_entry ,
  51 .Nm krb5_kt_get_name ,
  52 .Nm krb5_kt_get_type ,
  53 .Nm krb5_kt_next_entry ,
  54 .Nm krb5_kt_read_service_key ,
  55 .Nm krb5_kt_register ,
  56 .Nm krb5_kt_remove_entry ,
  57 .Nm krb5_kt_resolve ,
  58 .Nm krb5_kt_start_seq_get
  59 .Nd manage keytab (key storage) files
  60 .Sh LIBRARY
  61 Kerberos 5 Library (libkrb5, -lkrb5)
  62 .Sh SYNOPSIS
  63 .In krb5.h
  64 .Pp
  65 .Ft krb5_error_code
  66 .Fo krb5_kt_add_entry
  67 .Fa "krb5_context context"
  68 .Fa "krb5_keytab id"
  69 .Fa "krb5_keytab_entry *entry"
  70 .Fc
  71 .Ft krb5_error_code
  72 .Fo krb5_kt_close
  73 .Fa "krb5_context context"
  74 .Fa "krb5_keytab id"
  75 .Fc
  76 .Ft krb5_boolean
  77 .Fo krb5_kt_compare
  78 .Fa "krb5_context context"
  79 .Fa "krb5_keytab_entry *entry"
  80 .Fa "krb5_const_principal principal"
  81 .Fa "krb5_kvno vno"
  82 .Fa "krb5_enctype enctype"
  83 .Fc
  84 .Ft krb5_error_code
  85 .Fo krb5_kt_copy_entry_contents
  86 .Fa "krb5_context context"
  87 .Fa "const krb5_keytab_entry *in"
  88 .Fa "krb5_keytab_entry *out"
  89 .Fc
  90 .Ft krb5_error_code
  91 .Fo krb5_kt_default
  92 .Fa "krb5_context context"
  93 .Fa "krb5_keytab *id"
  94 .Fc
  95 .Ft krb5_error_code
  96 .Fo krb5_kt_default_modify_name
  97 .Fa "krb5_context context"
  98 .Fa "char *name"
  99 .Fa "size_t namesize"
 100 .Fc
 101 .Ft krb5_error_code
 102 .Fo krb5_kt_default_name
 103 .Fa "krb5_context context"
 104 .Fa "char *name"
 105 .Fa "size_t namesize"
 106 .Fc
 107 .Ft krb5_error_code
 108 .Fo krb5_kt_end_seq_get
 109 .Fa "krb5_context context"
 110 .Fa "krb5_keytab id"
 111 .Fa "krb5_kt_cursor *cursor"
 112 .Fc
 113 .Ft krb5_error_code
 114 .Fo krb5_kt_free_entry
 115 .Fa "krb5_context context"
 116 .Fa "krb5_keytab_entry *entry"
 117 .Fc
 118 .Ft krb5_error_code
 119 .Fo krb5_kt_get_entry
 120 .Fa "krb5_context context"
 121 .Fa "krb5_keytab id"
 122 .Fa "krb5_const_principal principal"
 123 .Fa "krb5_kvno kvno"
 124 .Fa "krb5_enctype enctype"
 125 .Fa "krb5_keytab_entry *entry"
 126 .Fc
 127 .Ft krb5_error_code
 128 .Fo krb5_kt_get_name
 129 .Fa "krb5_context context"
 130 .Fa "krb5_keytab keytab"
 131 .Fa "char *name"
 132 .Fa "size_t namesize"
 133 .Fc
 134 .Ft krb5_error_code
 135 .Fo krb5_kt_get_type
 136 .Fa "krb5_context context"
 137 .Fa "krb5_keytab keytab"
 138 .Fa "char *prefix"
 139 .Fa "size_t prefixsize"
 140 .Fc
 141 .Ft krb5_error_code
 142 .Fo krb5_kt_next_entry
 143 .Fa "krb5_context context"
 144 .Fa "krb5_keytab id"
 145 .Fa "krb5_keytab_entry *entry"
 146 .Fa "krb5_kt_cursor *cursor"
 147 .Fc
 148 .Ft krb5_error_code
 149 .Fo krb5_kt_read_service_key
 150 .Fa "krb5_context context"
 151 .Fa "krb5_pointer keyprocarg"
 152 .Fa "krb5_principal principal"
 153 .Fa "krb5_kvno vno"
 154 .Fa "krb5_enctype enctype"
 155 .Fa "krb5_keyblock **key"
 156 .Fc
 157 .Ft krb5_error_code
 158 .Fo krb5_kt_register
 159 .Fa "krb5_context context"
 160 .Fa "const krb5_kt_ops *ops"
 161 .Fc
 162 .Ft krb5_error_code
 163 .Fo krb5_kt_remove_entry
 164 .Fa "krb5_context context"
 165 .Fa "krb5_keytab id"
 166 .Fa "krb5_keytab_entry *entry"
 167 .Fc
 168 .Ft krb5_error_code
 169 .Fo krb5_kt_resolve
 170 .Fa "krb5_context context"
 171 .Fa "const char *name"
 172 .Fa "krb5_keytab *id"
 173 .Fc
 174 .Ft krb5_error_code
 175 .Fo krb5_kt_start_seq_get
 176 .Fa "krb5_context context"
 177 .Fa "krb5_keytab id"
 178 .Fa "krb5_kt_cursor *cursor"
 179 .Fc
 180 .Sh DESCRIPTION
 181 A keytab name is on the form
 182 .Li type:residual .
 183 The
 184 .Li residual
 185 part is specific to each keytab-type.
 186 .Pp
 187 When a keytab-name is resolved, the type is matched with an internal
 188 list of keytab types. If there is no matching keytab type,
 189 the default keytab is used. The current default type is
 190 .Nm file .
 191 The default value can be changed in the configuration file
 192 .Pa /etc/krb5.conf
 193 by setting the variable
 194 .Li [defaults]default_keytab_name .
 195 .Pp
 196 The keytab types that are implemented in Heimdal
 197 are:
 198 .Bl -tag -width Ds
 199 .It Nm file
 200 store the keytab in a file, the type's name is
 201 .Li FILE .
 202 The residual part is a filename.
 203 For compatibility with other Kerberos implemtation
 204 .Li WRFILE
 205 and
 206 .LI JAVA14
 207 is also accepted.
 208 .Li WRFILE
 209 has the same format as
 210 .Li FILE .
 211 .Li JAVA14
 212 have a format that is compatible with older versions of MIT kerberos
 213 and SUN's Java based installation.  They store a truncted kvno, so
 214 when the knvo excess 255, they are truncted in this format.
 215 .It Nm keyfile
 216 store the keytab in a
 217 .Li AFS
 218 keyfile (usually
 219 .Pa /usr/afs/etc/KeyFile ) ,
 220 the type's name is
 221 .Li AFSKEYFILE .
 222 The residual part is a filename.
 223 .It Nm krb4
 224 the keytab is a Kerberos 4
 225 .Pa srvtab
 226 that is on-the-fly converted to a keytab. The type's name is
 227 .Li krb4 .
 228 The residual part is a filename.
 229 .It Nm memory
 230 The keytab is stored in a memory segment. This allows sensitive and/or
 231 temporary data not to be stored on disk. The type's name is
 232 .Li MEMORY .
 233 Each
 234 .Li MEMORY
 235 keytab is referenced counted by and opened by the residual name, so two
 236 handles can point to the same memory area.
 237 When the last user closes the entry, it disappears.
 238 .El
 239 .Pp
 240 .Nm krb5_keytab_entry
 241 holds all data for an entry in a keytab file, like principal name,
 242 key-type, key, key-version number, etc.
 243 .Nm krb5_kt_cursor
 244 holds the current position that is used when iterating through a
 245 keytab entry with
 246 .Fn krb5_kt_start_seq_get ,
 247 .Fn krb5_kt_next_entry ,
 248 and
 249 .Fn krb5_kt_end_seq_get .
 250 .Pp
 251 .Nm krb5_kt_ops
 252 contains the different operations that can be done to a keytab. This
 253 structure is normally only used when doing a new keytab-type
 254 implementation.
 255 .Pp
 256 .Fn krb5_kt_resolve
 257 is the equivalent of an
 258 .Xr open 2
 259 on keytab. Resolve the keytab name in
 260 .Fa name
 261 into a keytab in
 262 .Fa id .
 263 Returns 0 or an error. The opposite of
 264 .Fn krb5_kt_resolve
 265 is
 266 .Fn krb5_kt_close .
 267 .Pp
 268 .Fn krb5_kt_close
 269 frees all resources allocated to the keytab, even on failure.
 270 Returns 0 or an error.
 271 .Pp
 272 .Fn krb5_kt_default
 273 sets the argument
 274 .Fa id
 275 to the default keytab.
 276 Returns 0 or an error.
 277 .Pp
 278 .Fn krb5_kt_default_modify_name
 279 copies the name of the default modify keytab into
 280 .Fa name .
 281 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
 282 .Fa namesize
 283 is too short.
 284 .Pp
 285 .Fn krb5_kt_default_name
 286 copies the name of the default keytab into
 287 .Fa name .
 288 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
 289 .Fa namesize
 290 is too short.
 291 .Pp
 292 .Fn krb5_kt_add_entry
 293 adds a new
 294 .Fa entry
 295 to the keytab
 296 .Fa id .
 297 .Li KRB5_KT_NOWRITE
 298 is returned if the keytab is a readonly keytab.
 299 .Pp
 300 .Fn krb5_kt_compare
 301 compares the passed in
 302 .Fa entry
 303 against
 304 .Fa principal ,
 305 .Fa vno ,
 306 and
 307 .Fa enctype .
 308 Any of
 309 .Fa principal ,
 310 .Fa vno
 311 or
 312 .Fa enctype
 313 might be 0 which acts as a wildcard. Return TRUE if they compare the
 314 same, FALSE otherwise.
 315 .Pp
 316 .Fn krb5_kt_copy_entry_contents
 317 copies the contents of
 318 .Fa in
 319 into
 320 .Fa out .
 321 Returns 0 or an error.
 322 .Pp
 323 .Fn krb5_kt_get_name
 324 retrieves the name of the keytab
 325 .Fa keytab
 326 into
 327 .Fa name ,
 328 .Fa namesize .
 329 Returns 0 or an error.
 330 .Pp
 331 .Fn krb5_kt_get_type
 332 retrieves the type of the keytab
 333 .Fa keytab
 334 and store the prefix/name for type of the keytab into
 335 .Fa prefix ,
 336 .Fa prefixsize .
 337 The prefix will have the maximum length of
 338 .Dv KRB5_KT_PREFIX_MAX_LEN
 339 (including terminating
 340 .Dv NUL ) .
 341 Returns 0 or an error.
 342 .Pp
 343 .Fn krb5_kt_free_entry
 344 frees the contents of
 345 .Fa entry .
 346 .Pp
 347 .Fn krb5_kt_start_seq_get
 348 sets
 349 .Fa cursor
 350 to point at the beginning of
 351 .Fa id .
 352 Returns 0 or an error.
 353 .Pp
 354 .Fn krb5_kt_next_entry
 355 gets the next entry from
 356 .Fa id
 357 pointed to by
 358 .Fa cursor
 359 and advance the
 360 .Fa cursor .
 361 On success the returne entry must be freed with
 362 .Fn krb5_kt_free_entry .
 363 Returns 0 or an error.
 364 .Pp
 365 .Fn krb5_kt_end_seq_get
 366 releases all resources associated with
 367 .Fa cursor .
 368 .Pp
 369 .Fn krb5_kt_get_entry
 370 retrieves the keytab entry for
 371 .Fa principal ,
 372 .Fa kvno ,
 373 .Fa enctype
 374 into
 375 .Fa entry
 376 from the keytab
 377 .Fa id .
 378 When comparing an entry in the keytab to determine a match, the
 379 function
 380 .Fn krb5_kt_compare
 381 is used, so the wildcard rules applies to the argument of
 382 .F krb5_kt_get_entry
 383 too.
 384 On success the returne entry must be freed with
 385 .Fn krb5_kt_free_entry .
 386 Returns 0 or an error.
 387 .Pp
 388 .Fn krb5_kt_read_service_key
 389 reads the key identified by
 390 .Fa ( principal ,
 391 .Fa vno ,
 392 .Fa enctype )
 393 from the keytab in
 394 .Fa keyprocarg
 395 (the system default keytab if
 396 .Dv NULL
 397 is used) into
 398 .Fa *key .
 399 .Fa keyprocarg
 400 is the same argument as to
 401 .Fa name
 402 argument to
 403 .Fn krb5_kt_resolve .
 404 Internal
 405 .Fn krb5_kt_compare
 406 will be used, so the same wildcard rules applies
 407 to
 408 .Fn krb5_kt_read_service_key .
 409 On success the returned key must be freed with
 410 .Fa krb5_free_keyblock .
 411 Returns 0 or an error.
 412 .Pp
 413 .Fn krb5_kt_remove_entry
 414 removes the entry
 415 .Fa entry
 416 from the keytab
 417 .Fa id .
 418 When comparing an entry in the keytab to determine a match, the
 419 function
 420 .Fn krb5_kt_compare
 421 is use, so the wildcard rules applies to the argument of
 422 .Fn krb5_kt_remove_entry .
 423 Returns 0,
 424 .Dv KRB5_KT_NOTFOUND
 425 if not entry matched or another error.
 426 .Pp
 427 .Fn krb5_kt_register
 428 registers a new keytab type
 429 .Fa ops .
 430 Returns 0 or an error.
 431 .Sh EXAMPLES
 432 This is a minimalistic version of
 433 .Nm ktutil .
 434 .Pp
 435 .Bd -literal
 436 int
 437 main (int argc, char **argv)
 438 {
 439     krb5_context context;
 440     krb5_keytab keytab;
 441     krb5_kt_cursor cursor;
 442     krb5_keytab_entry entry;
 443     krb5_error_code ret;
 444     char *principal;
 445
 446     if (krb5_init_context (&context) != 0)
 447         errx(1, "krb5_context");
 448
 449     ret = krb5_kt_default (context, &keytab);
 450     if (ret)
 451         krb5_err(context, 1, ret, "krb5_kt_default");
 452
 453     ret = krb5_kt_start_seq_get(context, keytab, &cursor);
 454     if (ret)
 455         krb5_err(context, 1, ret, "krb5_kt_start_seq_get");
 456     while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){
 457         krb5_unparse_name_short(context, entry.principal, &principal);
 458         printf("principal: %s\\n", principal);
 459         free(principal);
 460         krb5_kt_free_entry(context, &entry);
 461     }
 462     ret = krb5_kt_end_seq_get(context, keytab, &cursor);
 463     if (ret)
 464         krb5_err(context, 1, ret, "krb5_kt_end_seq_get");
 465     ret = krb5_kt_close(context, keytab);
 466     if (ret)
 467         krb5_err(context, 1, ret, "krb5_kt_close");
 468     krb5_free_context(context);
 469     return 0;
 470 }
 471 .Ed
 472 .Sh COMPATIBILITY
 473 Heimdal stored the ticket flags in machine bit-field order before
 474 Heimdal 0.7.  The behavior is possible to change in with the option
 475 .Li [libdefaults]fcc-mit-ticketflags .
 476 Heimdal 0.7 also code to detech that ticket flags was in the wrong
 477 order and correct them.  This matters when doing delegation in GSS-API
 478 because the client code looks at the flag to determin if it is possible
 479 to do delegation if the user requested it.
 480 .Sh SEE ALSO
 481 .Xr krb5.conf 5 ,
 482 .Xr kerberos 8