crypto/heimdal/lib/krb5/krb5_keytab.3

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