krb5_kt_start_seq_get(3)
NAME
krb5_kt_ops, krb5_keytab_entry, krb5_kt_cursor, krb5_kt_add_entry,
krb5_kt_close, krb5_kt_compare, krb5_kt_copy_entry_contents,
krb5_kt_default, krb5_kt_default_modify_name, krb5_kt_default_name,
krb5_kt_end_seq_get, krb5_kt_free_entry, krb5_kt_get_entry,
krb5_kt_get_name, krb5_kt_get_type, krb5_kt_next_entry,
krb5_kt_read_service_key, krb5_kt_register, krb5_kt_remove_entry,
krb5_kt_resolve, krb5_kt_start_seq_get -- manage keytab (key storage)
files
LIBRARY
Kerberos 5 Library (libkrb5, -lkrb5)
SYNOPSIS
#include <krb5.h>
krb5_error_code
krb5_kt_add_entry(krb5_context context, krb5_keytab id,
krb5_keytab_entry *entry);
krb5_error_code
krb5_kt_close(krb5_context context, krb5_keytab id);
krb5_boolean
krb5_kt_compare(krb5_context context, krb5_keytab_entry *entry,
krb5_const_principal principal, krb5_kvno vno, krb5_enctype enctype);
krb5_error_code
krb5_kt_copy_entry_contents(krb5_context context,
const krb5_keytab_entry *in, krb5_keytab_entry *out);
krb5_error_code
krb5_kt_default(krb5_context context, krb5_keytab *id);
krb5_error_code
krb5_kt_default_modify_name(krb5_context context, char *name,
size_t namesize);
krb5_error_code
krb5_kt_default_name(krb5_context context, char *name, size_t namesize);
krb5_error_code
krb5_kt_end_seq_get(krb5_context context, krb5_keytab id,
krb5_kt_cursor *cursor);
krb5_error_code
krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
krb5_error_code
krb5_kt_get_entry(krb5_context context, krb5_keytab id,
krb5_const_principal principal, krb5_kvno kvno, krb5_enctype enctype,
krb5_keytab_entry *entry);
krb5_error_code
krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name,
size_t namesize);
krb5_error_code
krb5_kt_get_type(krb5_context context, krb5_keytab keytab, char *prefix,
size_t prefixsize);
krb5_error_code
krb5_kt_next_entry(krb5_context context, krb5_keytab id,
krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
krb5_error_code
krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
krb5_principal principal, krb5_kvno vno, krb5_enctype enctype,
krb5_keyblock **key);
krb5_error_code
krb5_kt_register(krb5_context context, const krb5_kt_ops *ops);
krb5_error_code
krb5_kt_remove_entry(krb5_context context, krb5_keytab id,
krb5_keytab_entry *entry);
krb5_error_code
krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *id);
krb5_error_code
krb5_kt_start_seq_get(krb5_context context, krb5_keytab id,
krb5_kt_cursor *cursor);
DESCRIPTION
A keytab name is on the form type:residual. The residual part is spe-
cific to each keytab-type.
When a keytab-name is resolved, the type is matched with an internal list
of keytab types. If there is no matching keytab type, the default keytab
is used. The current default type is file. The default value can be
changed in the configuration file /etc/krb5.conf by setting the variable
[defaults]default_keytab_name.
The keytab types that are implemented in Heimdal are:
file store the keytab in a file, the type's name is FILE. The resid-
ual part is a filename. For compatibility with other Kerberos
implemtation WRFILE and is also accepted. WRFILE has the same
format as FILE. JAVA14 have a format that is compatible with
older versions of MIT kerberos and SUN's Java based installation.
They store a truncted kvno, so when the knvo excess 255, they are
truncted in this format.
keyfile
store the keytab in a AFS keyfile (usually /usr/afs/etc/KeyFile),
the type's name is AFSKEYFILE. The residual part is a filename.
krb4 the keytab is a Kerberos 4 srvtab that is on-the-fly converted to
a keytab. The type's name is krb4. The residual part is a file-
name.
memory The keytab is stored in a memory segment. This allows sensitive
and/or temporary data not to be stored on disk. The type's name
is MEMORY. Each MEMORY keytab is referenced counted by and
opened by the residual name, so two handles can point to the same
memory area. When the last user closes the entry, it disappears.
krb5_keytab_entry holds all data for an entry in a keytab file, like
principal name, key-type, key, key-version number, etc. krb5_kt_cursor
holds the current position that is used when iterating through a keytab
entry with krb5_kt_start_seq_get(), krb5_kt_next_entry(), and
krb5_kt_end_seq_get().
krb5_kt_ops contains the different operations that can be done to a
keytab. This structure is normally only used when doing a new keytab-type
implementation.
krb5_kt_resolve() is the equivalent of an open(2) on keytab. Resolve the
keytab name in name into a keytab in id. Returns 0 or an error. The
opposite of krb5_kt_resolve() is krb5_kt_close().
krb5_kt_close() frees all resources allocated to the keytab, even on
failure. Returns 0 or an error.
krb5_kt_default() sets the argument id to the default keytab. Returns 0
or an error.
krb5_kt_default_modify_name() copies the name of the default modify
keytab into name. Return 0 or KRB5_CONFIG_NOTENUFSPACE if namesize is
too short.
krb5_kt_default_name() copies the name of the default keytab into name.
Return 0 or KRB5_CONFIG_NOTENUFSPACE if namesize is too short.
krb5_kt_add_entry() adds a new entry to the keytab id. KRB5_KT_NOWRITE
is returned if the keytab is a readonly keytab.
krb5_kt_compare() compares the passed in entry against principal, vno,
and enctype. Any of principal, vno or enctype might be 0 which acts as a
wildcard. Return TRUE if they compare the same, FALSE otherwise.
krb5_kt_copy_entry_contents() copies the contents of in into out.
Returns 0 or an error.
krb5_kt_get_name() retrieves the name of the keytab keytab into name,
namesize. Returns 0 or an error.
krb5_kt_get_type() retrieves the type of the keytab keytab and store the
prefix/name for type of the keytab into prefix, prefixsize. The prefix
will have the maximum length of KRB5_KT_PREFIX_MAX_LEN (including termi-
nating NUL). Returns 0 or an error.
krb5_kt_free_entry() frees the contents of entry.
krb5_kt_start_seq_get() sets cursor to point at the beginning of id.
Returns 0 or an error.
krb5_kt_next_entry() gets the next entry from id pointed to by cursor and
advance the cursor. On success the returne entry must be freed with
krb5_kt_free_entry(). Returns 0 or an error.
krb5_kt_end_seq_get() releases all resources associated with cursor.
krb5_kt_get_entry() retrieves the keytab entry for principal, kvno,
enctype into entry from the keytab id. When comparing an entry in the
keytab to determine a match, the function krb5_kt_compare() is used, so
the wildcard rules applies to the argument of too. On success the
returne entry must be freed with krb5_kt_free_entry(). Returns 0 or an
error.
krb5_kt_read_service_key() reads the key identified by (principal, vno,
enctype) from the keytab in keyprocarg (the system default keytab if NULL
is used) into *key. keyprocarg is the same argument as to name argument
to krb5_kt_resolve(). Internal krb5_kt_compare() will be used, so the
same wildcard rules applies to krb5_kt_read_service_key(). On success
the returned key must be freed with krb5_free_keyblock. Returns 0 or an
error.
krb5_kt_remove_entry() removes the entry entry from the keytab id. When
comparing an entry in the keytab to determine a match, the function
krb5_kt_compare() is use, so the wildcard rules applies to the argument
of krb5_kt_remove_entry(). Returns 0, KRB5_KT_NOTFOUND if not entry
matched or another error.
krb5_kt_register() registers a new keytab type ops. Returns 0 or an
error.
EXAMPLES
This is a minimalistic version of ktutil.
int
main (int argc, char **argv)
{
krb5_context context;
krb5_keytab keytab;
krb5_kt_cursor cursor;
krb5_keytab_entry entry;
krb5_error_code ret;
char *principal;
if (krb5_init_context (&context) != 0)
errx(1, "krb5_context");
ret = krb5_kt_default (context, &keytab);
if (ret)
krb5_err(context, 1, ret, "krb5_kt_default");
ret = krb5_kt_start_seq_get(context, keytab, &cursor);
if (ret)
krb5_err(context, 1, ret, "krb5_kt_start_seq_get");
while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){
krb5_unparse_name_short(context, entry.principal, &principal);
printf("principal: %s\n", principal);
free(principal);
krb5_kt_free_entry(context, &entry);
}
ret = krb5_kt_end_seq_get(context, keytab, &cursor);
if (ret)
krb5_err(context, 1, ret, "krb5_kt_end_seq_get");
ret = krb5_kt_close(context, keytab);
if (ret)
krb5_err(context, 1, ret, "krb5_kt_close");
krb5_free_context(context);
return 0;
}
COMPATIBILITY
Heimdal stored the ticket flags in machine bit-field order before Heimdal
0.7. The behavior is possible to change in with the option
[libdefaults]fcc-mit-ticketflags. Heimdal 0.7 also code to detech that
ticket flags was in the wrong order and correct them. This matters when
doing delegation in GSS-API because the client code looks at the flag to
determin if it is possible to do delegation if the user requested it.
SEE ALSO
krb5.conf(5), kerberos(8)
HEIMDAL August 12, 2005 HEIMDAL
Man(1) output converted with
man2html