diff options
Diffstat (limited to 'lib/krb5/krb5_keytab.3')
| -rw-r--r-- | lib/krb5/krb5_keytab.3 | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/lib/krb5/krb5_keytab.3 b/lib/krb5/krb5_keytab.3 new file mode 100644 index 0000000..b6cb1a2 --- /dev/null +++ b/lib/krb5/krb5_keytab.3 @@ -0,0 +1,482 @@ +.\" Copyright (c) 2001 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: krb5_keytab.3 22071 2007-11-14 20:04:50Z lha $ +.\" +.Dd August 12, 2005 +.Dt KRB5_KEYTAB 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_kt_ops , +.Nm krb5_keytab_entry , +.Nm krb5_kt_cursor , +.Nm krb5_kt_add_entry , +.Nm krb5_kt_close , +.Nm krb5_kt_compare , +.Nm krb5_kt_copy_entry_contents , +.Nm krb5_kt_default , +.Nm krb5_kt_default_modify_name , +.Nm krb5_kt_default_name , +.Nm krb5_kt_end_seq_get , +.Nm krb5_kt_free_entry , +.Nm krb5_kt_get_entry , +.Nm krb5_kt_get_name , +.Nm krb5_kt_get_type , +.Nm krb5_kt_next_entry , +.Nm krb5_kt_read_service_key , +.Nm krb5_kt_register , +.Nm krb5_kt_remove_entry , +.Nm krb5_kt_resolve , +.Nm krb5_kt_start_seq_get +.Nd manage keytab (key storage) files +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5.h +.Pp +.Ft krb5_error_code +.Fo krb5_kt_add_entry +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_keytab_entry *entry" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_close +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fc +.Ft krb5_boolean +.Fo krb5_kt_compare +.Fa "krb5_context context" +.Fa "krb5_keytab_entry *entry" +.Fa "krb5_const_principal principal" +.Fa "krb5_kvno vno" +.Fa "krb5_enctype enctype" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_copy_entry_contents +.Fa "krb5_context context" +.Fa "const krb5_keytab_entry *in" +.Fa "krb5_keytab_entry *out" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_default +.Fa "krb5_context context" +.Fa "krb5_keytab *id" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_default_modify_name +.Fa "krb5_context context" +.Fa "char *name" +.Fa "size_t namesize" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_default_name +.Fa "krb5_context context" +.Fa "char *name" +.Fa "size_t namesize" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_end_seq_get +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_kt_cursor *cursor" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_free_entry +.Fa "krb5_context context" +.Fa "krb5_keytab_entry *entry" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_get_entry +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_const_principal principal" +.Fa "krb5_kvno kvno" +.Fa "krb5_enctype enctype" +.Fa "krb5_keytab_entry *entry" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_get_name +.Fa "krb5_context context" +.Fa "krb5_keytab keytab" +.Fa "char *name" +.Fa "size_t namesize" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_get_type +.Fa "krb5_context context" +.Fa "krb5_keytab keytab" +.Fa "char *prefix" +.Fa "size_t prefixsize" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_next_entry +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_keytab_entry *entry" +.Fa "krb5_kt_cursor *cursor" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_read_service_key +.Fa "krb5_context context" +.Fa "krb5_pointer keyprocarg" +.Fa "krb5_principal principal" +.Fa "krb5_kvno vno" +.Fa "krb5_enctype enctype" +.Fa "krb5_keyblock **key" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_register +.Fa "krb5_context context" +.Fa "const krb5_kt_ops *ops" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_remove_entry +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_keytab_entry *entry" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_resolve +.Fa "krb5_context context" +.Fa "const char *name" +.Fa "krb5_keytab *id" +.Fc +.Ft krb5_error_code +.Fo krb5_kt_start_seq_get +.Fa "krb5_context context" +.Fa "krb5_keytab id" +.Fa "krb5_kt_cursor *cursor" +.Fc +.Sh DESCRIPTION +A keytab name is on the form +.Li type:residual . +The +.Li residual +part is specific to each keytab-type. +.Pp +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 +.Nm file . +The default value can be changed in the configuration file +.Pa /etc/krb5.conf +by setting the variable +.Li [defaults]default_keytab_name . +.Pp +The keytab types that are implemented in Heimdal +are: +.Bl -tag -width Ds +.It Nm file +store the keytab in a file, the type's name is +.Li FILE . +The residual part is a filename. +For compatibility with other Kerberos implemtation +.Li WRFILE +and +.LI JAVA14 +is also accepted. +.Li WRFILE +has the same format as +.Li FILE . +.Li 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. +.It Nm keyfile +store the keytab in a +.Li AFS +keyfile (usually +.Pa /usr/afs/etc/KeyFile ) , +the type's name is +.Li AFSKEYFILE . +The residual part is a filename. +.It Nm krb4 +the keytab is a Kerberos 4 +.Pa srvtab +that is on-the-fly converted to a keytab. The type's name is +.Li krb4 . +The residual part is a filename. +.It Nm 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 +.Li MEMORY . +Each +.Li 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. +.El +.Pp +.Nm krb5_keytab_entry +holds all data for an entry in a keytab file, like principal name, +key-type, key, key-version number, etc. +.Nm krb5_kt_cursor +holds the current position that is used when iterating through a +keytab entry with +.Fn krb5_kt_start_seq_get , +.Fn krb5_kt_next_entry , +and +.Fn krb5_kt_end_seq_get . +.Pp +.Nm 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. +.Pp +.Fn krb5_kt_resolve +is the equivalent of an +.Xr open 2 +on keytab. Resolve the keytab name in +.Fa name +into a keytab in +.Fa id . +Returns 0 or an error. The opposite of +.Fn krb5_kt_resolve +is +.Fn krb5_kt_close . +.Pp +.Fn krb5_kt_close +frees all resources allocated to the keytab, even on failure. +Returns 0 or an error. +.Pp +.Fn krb5_kt_default +sets the argument +.Fa id +to the default keytab. +Returns 0 or an error. +.Pp +.Fn krb5_kt_default_modify_name +copies the name of the default modify keytab into +.Fa name . +Return 0 or KRB5_CONFIG_NOTENUFSPACE if +.Fa namesize +is too short. +.Pp +.Fn krb5_kt_default_name +copies the name of the default keytab into +.Fa name . +Return 0 or KRB5_CONFIG_NOTENUFSPACE if +.Fa namesize +is too short. +.Pp +.Fn krb5_kt_add_entry +adds a new +.Fa entry +to the keytab +.Fa id . +.Li KRB5_KT_NOWRITE +is returned if the keytab is a readonly keytab. +.Pp +.Fn krb5_kt_compare +compares the passed in +.Fa entry +against +.Fa principal , +.Fa vno , +and +.Fa enctype . +Any of +.Fa principal , +.Fa vno +or +.Fa enctype +might be 0 which acts as a wildcard. Return TRUE if they compare the +same, FALSE otherwise. +.Pp +.Fn krb5_kt_copy_entry_contents +copies the contents of +.Fa in +into +.Fa out . +Returns 0 or an error. +.Pp +.Fn krb5_kt_get_name +retrieves the name of the keytab +.Fa keytab +into +.Fa name , +.Fa namesize . +Returns 0 or an error. +.Pp +.Fn krb5_kt_get_type +retrieves the type of the keytab +.Fa keytab +and store the prefix/name for type of the keytab into +.Fa prefix , +.Fa prefixsize . +The prefix will have the maximum length of +.Dv KRB5_KT_PREFIX_MAX_LEN +(including terminating +.Dv NUL ) . +Returns 0 or an error. +.Pp +.Fn krb5_kt_free_entry +frees the contents of +.Fa entry . +.Pp +.Fn krb5_kt_start_seq_get +sets +.Fa cursor +to point at the beginning of +.Fa id . +Returns 0 or an error. +.Pp +.Fn krb5_kt_next_entry +gets the next entry from +.Fa id +pointed to by +.Fa cursor +and advance the +.Fa cursor . +On success the returne entry must be freed with +.Fn krb5_kt_free_entry . +Returns 0 or an error. +.Pp +.Fn krb5_kt_end_seq_get +releases all resources associated with +.Fa cursor . +.Pp +.Fn krb5_kt_get_entry +retrieves the keytab entry for +.Fa principal , +.Fa kvno , +.Fa enctype +into +.Fa entry +from the keytab +.Fa id . +When comparing an entry in the keytab to determine a match, the +function +.Fn krb5_kt_compare +is used, so the wildcard rules applies to the argument of +.F krb5_kt_get_entry +too. +On success the returne entry must be freed with +.Fn krb5_kt_free_entry . +Returns 0 or an error. +.Pp +.Fn krb5_kt_read_service_key +reads the key identified by +.Fa ( principal , +.Fa vno , +.Fa enctype ) +from the keytab in +.Fa keyprocarg +(the system default keytab if +.Dv NULL +is used) into +.Fa *key . +.Fa keyprocarg +is the same argument as to +.Fa name +argument to +.Fn krb5_kt_resolve . +Internal +.Fn krb5_kt_compare +will be used, so the same wildcard rules applies +to +.Fn krb5_kt_read_service_key . +On success the returned key must be freed with +.Fa krb5_free_keyblock . +Returns 0 or an error. +.Pp +.Fn krb5_kt_remove_entry +removes the entry +.Fa entry +from the keytab +.Fa id . +When comparing an entry in the keytab to determine a match, the +function +.Fn krb5_kt_compare +is use, so the wildcard rules applies to the argument of +.Fn krb5_kt_remove_entry . +Returns 0, +.Dv KRB5_KT_NOTFOUND +if not entry matched or another error. +.Pp +.Fn krb5_kt_register +registers a new keytab type +.Fa ops . +Returns 0 or an error. +.Sh EXAMPLES +This is a minimalistic version of +.Nm ktutil . +.Pp +.Bd -literal +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; +} +.Ed +.Sh 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 +.Li [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. +.Sh SEE ALSO +.Xr krb5.conf 5 , +.Xr kerberos 8 |
