August 12, 2005 KRB5_KEYTAB 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

```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 specific 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 residual 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 filename.

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 terminating ```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)