From 2f0477a0b54a1ef66276438d628c96d1f8cf0e95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Love=20H=C3=B6rnquist=20=C3=85strand?= Date: Tue, 18 Oct 2005 20:11:25 +0000 Subject: [PATCH] Try to explain krb5_ccache, krb5_principal and errors. git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@16180 ec53bebd-3082-4978-b11e-865c3cabbd6b --- doc/programming.texi | 54 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/doc/programming.texi b/doc/programming.texi index 0a25494bf..5e43195ed 100644 --- a/doc/programming.texi +++ b/doc/programming.texi @@ -16,14 +16,15 @@ introduction text (@pxref{What is Kerberos?}). @node Kerberos 5 API Overview, Walkthru a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos @section Kerberos 5 API Overview -Most functions are documenteded in manual pages. This overview only -tries to point to where to look for a specific function. +All functions are documenteded in manual pages. This section tries to +give an overview of the major components used in Kerberos library, and +point to where to look for a specific function. @subsection Kerberos context A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that are context specific are stored in this struture, including default -encryption types, credential-cache (ticket file), and default realms. +encryption types, credential cache (for example, a ticket file), and default realms. See the manual pages for @manpage{krb5_context,3} and @manpage{krb5_init_context,3}. @@ -42,18 +43,57 @@ replay cache, and checksum types. See the manual page for @manpage{krb5_auth_context,3}. +@subsection Kerberos principal + +The Kerberos principal is the structure that identifies a user or +service in Kerberos. The structure that holds the principal is the +@code{krb5_principal}. There are function os extract the realm and +elements of the principal, but Most applications have no reason to +inspect the content of the structure. + +The are several ways to create a principal (with diffrent degree of +portibility), and one way to free it. + +See manual page for @manpage{krb5_principal,3} for more information +about the functions. + +@subsection Credential cache + +A credential cache holds the tickets for a user. A given user can have +several credential caches, one for each realm where the user have the +initial tickets (the first krbtgt). + +The credential cache data can be store several diffrent way, each for +diffrent proposes. File credential (FILE) caches and processes based +(KCM) caches are for permanent storage, while memory caches (MEMORY) +are local caches to the local process. + +Caches are opened with @manpage{krb5_cc_resolve,3} or created with +@manpage{krb5_cc_gen_unique,3}. + +If the cache needs to be opened again (using +@manpage{krb5_cc_resolve,3}) @manpage{krb5_cc_close,3} will close the +handle, but not the remove the cache. @manpage{krb5_cc_destroy,3} will +zero out the cache, remove the cache so it can no longer be +referenced. + +See also manual page for @manpage{krb5_ccache,3} + +@subsection Kerberos errors + +See also manual page for @manpage{krb5_get_error_string,3} and +@manpage{krb5_get_err_text,3}. + @subsection Keytab management A keytab is a storage for locally stored keys. Heimdal includes keytab support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, and for storing keys in memory. +Keytabs are used for servers and long-running services. + See also manual page for @manpage{krb5_keytab,3} -@subsection Kerberos principal - -See also manual page for @manpage{krb5_principal,3} - @subsection Kerberos crypto See also manual page for @manpage{krb5_crypto_init,3},