crypto/heimdal/lib/krb5/krb5_keytab.3

   1 .\" Copyright (c) 2001 - 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_keytab.3,v 1.9 2003/04/16 13:58:16 lha Exp $
  33 .\"
  34 .Dd February 5, 2001
  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_name ,
  47 .Nm krb5_kt_end_seq_get ,
  48 .Nm krb5_kt_free_entry ,
  49 .Nm krb5_kt_get_entry ,
  50 .Nm krb5_kt_get_name ,
  51 .Nm krb5_kt_get_type ,
  52 .Nm krb5_kt_next_entry ,
  53 .Nm krb5_kt_read_service_key ,
  54 .Nm krb5_kt_register ,
  55 .Nm krb5_kt_remove_entry ,
  56 .Nm krb5_kt_resolve ,
  57 .Nm krb5_kt_start_seq_get
  58 .Nd manage keytab (key storage) files
  59 .Sh LIBRARY
  60 Kerberos 5 Library (libkrb5, -lkrb5)
  61 .Sh SYNOPSIS
  62 .In krb5.h
  63 .Pp
  64 .Ft krb5_error_code
  65 .Fo krb5_kt_add_entry
  66 .Fa "krb5_context context"
  67 .Fa "krb5_keytab id"
  68 .Fa "krb5_keytab_entry *entry"
  69 .Fc
  70 .Ft krb5_error_code
  71 .Fo krb5_kt_close
  72 .Fa "krb5_context context"
  73 .Fa "krb5_keytab id"
  74 .Fc
  75 .Ft krb5_boolean
  76 .Fo krb5_kt_compare
  77 .Fa "krb5_context context"
  78 .Fa "krb5_keytab_entry *entry"
  79 .Fa "krb5_const_principal principal"
  80 .Fa "krb5_kvno vno"
  81 .Fa "krb5_enctype enctype"
  82 .Fc
  83 .Ft krb5_error_code
  84 .Fo krb5_kt_copy_entry_contents
  85 .Fa "krb5_context context"
  86 .Fa "const krb5_keytab_entry *in"
  87 .Fa "krb5_keytab_entry *out"
  88 .Fc
  89 .Ft krb5_error_code
  90 .Fo krb5_kt_default
  91 .Fa "krb5_context context"
  92 .Fa "krb5_keytab *id"
  93 .Fc
  94 .Ft krb5_error_code
  95 .Fo krb5_kt_default_name
  96 .Fa "krb5_context context"
  97 .Fa "char *name"
  98 .Fa "size_t namesize"
  99 .Fc
 100 .Ft krb5_error_code
 101 .Fo krb5_kt_end_seq_get
 102 .Fa "krb5_context context"
 103 .Fa "krb5_keytab id"
 104 .Fa "krb5_kt_cursor *cursor"
 105 .Fc
 106 .Ft krb5_error_code
 107 .Fo krb5_kt_free_entry
 108 .Fa "krb5_context context"
 109 .Fa "krb5_keytab_entry *entry"
 110 .Fc
 111 .Ft krb5_error_code
 112 .Fo krb5_kt_get_entry
 113 .Fa "krb5_context context"
 114 .Fa "krb5_keytab id"
 115 .Fa "krb5_const_principal principal"
 116 .Fa "krb5_kvno kvno"
 117 .Fa "krb5_enctype enctype"
 118 .Fa "krb5_keytab_entry *entry"
 119 .Fc
 120 .Ft krb5_error_code
 121 .Fo krb5_kt_get_name
 122 .Fa "krb5_context context"
 123 .Fa "krb5_keytab keytab"
 124 .Fa "char *name"
 125 .Fa "size_t namesize"
 126 .Fc
 127 .Ft krb5_error_code
 128 .Fo krb5_kt_get_type
 129 .Fa "krb5_context context"
 130 .Fa "krb5_keytab keytab"
 131 .Fa "char *prefix"
 132 .Fa "size_t prefixsize"
 133 .Fc
 134 .Ft krb5_error_code
 135 .Fo krb5_kt_next_entry
 136 .Fa "krb5_context context"
 137 .Fa "krb5_keytab id"
 138 .Fa "krb5_keytab_entry *entry"
 139 .Fa "krb5_kt_cursor *cursor"
 140 .Fc
 141 .Ft krb5_error_code
 142 .Fo krb5_kt_read_service_key
 143 .Fa "krb5_context context"
 144 .Fa "krb5_pointer keyprocarg"
 145 .Fa "krb5_principal principal"
 146 .Fa "krb5_kvno vno"
 147 .Fa "krb5_enctype enctype"
 148 .Fa "krb5_keyblock **key"
 149 .Fc
 150 .Ft krb5_error_code
 151 .Fo krb5_kt_register
 152 .Fa "krb5_context context"
 153 .Fa "const krb5_kt_ops *ops"
 154 .Fc
 155 .Ft krb5_error_code
 156 .Fo krb5_kt_remove_entry
 157 .Fa "krb5_context context"
 158 .Fa "krb5_keytab id"
 159 .Fa "krb5_keytab_entry *entry"
 160 .Fc
 161 .Ft krb5_error_code
 162 .Fo krb5_kt_resolve
 163 .Fa "krb5_context context"
 164 .Fa "const char *name"
 165 .Fa "krb5_keytab *id"
 166 .Fc
 167 .Ft krb5_error_code
 168 .Fo krb5_kt_start_seq_get
 169 .Fa "krb5_context context"
 170 .Fa "krb5_keytab id"
 171 .Fa "krb5_kt_cursor *cursor"
 172 .Fc
 173 .Sh DESCRIPTION
 174 A keytab name is on the form
 175 .Li type:residual .
 176 The
 177 .Li residual
 178 part is specific to each keytab-type.
 179 .Pp
 180 When a keytab-name is resolved, the type is matched with an internal
 181 list of keytab types. If there is no matching keytab type,
 182 the default keytab is used. The current default type is
 183 .Nm file .
 184 The default value can be changed in the configuration file
 185 .Pa /etc/krb5.conf
 186 by setting the variable
 187 .Li [defaults]default_keytab_name .
 188 .Pp
 189 The keytab types that are implemented in Heimdal
 190 are:
 191 .Bl -tag -width Ds
 192 .It Nm file
 193 store the keytab in a file, the type's name is
 194 .Li KEYFILE .
 195 The residual part is a filename.
 196 .It Nm keyfile
 197 store the keytab in a
 198 .Li AFS
 199 keyfile (usually
 200 .Pa /usr/afs/etc/KeyFile ) ,
 201 the type's name is
 202 .Li AFSKEYFILE .
 203 The residual part is a filename.
 204 .It Nm krb4
 205 the keytab is a Kerberos 4
 206 .Pa srvtab
 207 that is on-the-fly converted to a keytab. The type's name is
 208 .Li krb4 .
 209 The residual part is a filename.
 210 .It Nm memory
 211 The keytab is stored in a memory segment. This allows sensitive and/or
 212 temporary data not to be stored on disk. The type's name is
 213 .Li MEMORY .
 214 There are no residual part, the only pointer back to the keytab is the
 215 .Fa id
 216 returned by
 217 .Fn krb5_kt_resolve .
 218 .El
 219 .Pp
 220 .Nm krb5_keytab_entry
 221 holds all data for an entry in a keytab file, like principal name,
 222 key-type, key, key-version number, etc.
 223 .Nm krb5_kt_cursor
 224 holds the current position that is used when iterating through a
 225 keytab entry with
 226 .Fn krb5_kt_start_seq_get ,
 227 .Fn krb5_kt_next_entry ,
 228 and
 229 .Fn krb5_kt_end_seq_get .
 230 .Pp
 231 .Nm krb5_kt_ops
 232 contains the different operations that can be done to a keytab. This
 233 structure is normally only used when doing a new keytab-type
 234 implementation.
 235 .Pp
 236 .Fn krb5_kt_resolve
 237 is the equivalent of an
 238 .Xr open 2
 239 on keytab. Resolve the keytab name in
 240 .Fa name
 241 into a keytab in
 242 .Fa id .
 243 Returns 0 or an error. The opposite of
 244 .Fn krb5_kt_resolve
 245 is
 246 .Fn krb5_kt_close .
 247 .Fn krb5_kt_close
 248 frees all resources allocated to the keytab.
 249 .Pp
 250 .Fn krb5_kt_default
 251 sets the argument
 252 .Fa id
 253 to the default keytab.
 254 Returns 0 or an error.
 255 .Pp
 256 .Fn krb5_kt_default_name
 257 copy the name of the default keytab into
 258 .Fa name .
 259 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
 260 .Fa namesize
 261 is too short.
 262 .Pp
 263 .Fn krb5_kt_add_entry
 264 Add a new
 265 .Fa entry
 266 to the keytab
 267 .Fa id .
 268 .Li KRB5_KT_NOWRITE
 269 is returned if the keytab is a readonly keytab.
 270 .Pp
 271 .Fn krb5_kt_compare
 272 compares the passed in
 273 .Fa entry
 274 against
 275 .Fa principal ,
 276 .Fa vno ,
 277 and
 278 .Fa enctype .
 279 Any of
 280 .Fa principal ,
 281 .Fa vno
 282 or
 283 .Fa enctype
 284 might be 0 which acts as a wildcard. Return TRUE if they compare the
 285 same, FALSE otherwise.
 286 .Pp
 287 .Fn krb5_kt_copy_entry_contents
 288 copies the contents of
 289 .Fa in
 290 into
 291 .Fa out .
 292 Returns 0 or an error.
 293 .Pp
 294 .Fn krb5_kt_get_name
 295 retrieves the name of the keytab
 296 .Fa keytab
 297 into
 298 .Fa name ,
 299 .Fa namesize .
 300 Returns 0 or an error.
 301 .Pp
 302 .Fn krb5_kt_get_type
 303 retrieves the type of the keytab
 304 .Fa keytab
 305 and store the prefix/name for type of the keytab into
 306 .Fa prefix ,
 307 .Fa prefixsize .
 308 The prefix will have the maximum length of
 309 .Dv KRB5_KT_PREFIX_MAX_LEN
 310 (including terminating
 311 .Dv NUL ) .
 312 Returns 0 or an error.
 313 .Pp
 314 .Fn krb5_kt_free_entry
 315 frees the contents of
 316 .Fa entry .
 317 .Pp
 318 .Fn krb5_kt_start_seq_get
 319 sets
 320 .Fa cursor
 321 to point at the beginning of
 322 .Fa id .
 323 Returns 0 or an error.
 324 .Pp
 325 .Fn krb5_kt_next_entry
 326 gets the next entry from
 327 .Fa id
 328 pointed to by
 329 .Fa cursor
 330 and advance the
 331 .Fa cursor .
 332 Returns 0 or an error.
 333 .Pp
 334 .Fn krb5_kt_end_seq_get
 335 releases all resources associated with
 336 .Fa cursor .
 337 .Pp
 338 .Fn krb5_kt_get_entry
 339 retrieves the keytab entry for
 340 .Fa principal ,
 341 .Fa kvno,
 342 .Fa enctype
 343 into
 344 .Fa entry
 345 from the keytab
 346 .Fa id .
 347 Returns 0 or an error.
 348 .Pp
 349 .Fn krb5_kt_read_service_key
 350 reads the key identified by
 351 .Ns ( Fa principal ,
 352 .Fa vno ,
 353 .Fa enctype )
 354 from the keytab in
 355 .Fa keyprocarg
 356 (the default if == NULL) into
 357 .Fa *key .
 358 Returns 0 or an error.
 359 .Pp
 360 .Fn krb5_kt_remove_entry
 361 removes the entry
 362 .Fa entry
 363 from the keytab
 364 .Fa id .
 365 Returns 0 or an error.
 366 .Pp
 367 .Fn krb5_kt_register
 368 registers a new keytab type
 369 .Fa ops .
 370 Returns 0 or an error.
 371 .Sh EXAMPLE
 372 This is a minimalistic version of
 373 .Nm ktutil .
 374 .Pp
 375 .Bd -literal
 376 int
 377 main (int argc, char **argv)
 378 {
 379     krb5_context context;
 380     krb5_keytab keytab;
 381     krb5_kt_cursor cursor;
 382     krb5_keytab_entry entry;
 383     krb5_error_code ret;
 384     char *principal;
 385
 386     if (krb5_init_context (&context) != 0)
 387         errx(1, "krb5_context");
 388
 389     ret = krb5_kt_default (context, &keytab);
 390     if (ret)
 391         krb5_err(context, 1, ret, "krb5_kt_default");
 392
 393     ret = krb5_kt_start_seq_get(context, keytab, &cursor);
 394     if (ret)
 395         krb5_err(context, 1, ret, "krb5_kt_start_seq_get");
 396     while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){
 397         krb5_unparse_name_short(context, entry.principal, &principal);
 398         printf("principal: %s\\n", principal);
 399         free(principal);
 400         krb5_kt_free_entry(context, &entry);
 401     }
 402     ret = krb5_kt_end_seq_get(context, keytab, &cursor);
 403     if (ret)
 404         krb5_err(context, 1, ret, "krb5_kt_end_seq_get");
 405     krb5_free_context(context);
 406     return 0;
 407 }
 408 .Ed
 409 .Sh SEE ALSO
 410 .Xr krb5.conf 5 ,
 411 .Xr kerberos 8