From: Alexandra Ellwood Date: Wed, 7 May 2008 19:40:32 +0000 (+0000) Subject: Added kim documentation X-Git-Tag: krb5-1.7-alpha1~686 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=39cae9c5f63ff24e24cffabe223a6c253bfa7503;p=thirdparty%2Fkrb5.git Added kim documentation ticket: 5960 git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20315 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/kim/Doxyfile b/doc/kim/Doxyfile new file mode 100644 index 0000000000..fbaf3726ba --- /dev/null +++ b/doc/kim/Doxyfile @@ -0,0 +1,281 @@ +# Doxyfile 1.5.3 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Kerberos Identity Management " +PROJECT_NUMBER = +OUTPUT_DIRECTORY = . +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class " \ + "The $name widget " \ + "The $name file " \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = YES +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = YES +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = NO +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = NO +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_FORMAT = "$file:$line: $text " +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = ../../src/include/kim +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.C \ + *.CC \ + *.C++ \ + *.II \ + *.I++ \ + *.H \ + *.HH \ + *.H++ \ + *.CS \ + *.PHP \ + *.PHP3 \ + *.M \ + *.MM \ + *.PY +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = NO +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = NO +GENERATE_HTMLHELP = NO +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = YES +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = letter +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = YES +RTF_OUTPUT = rtf +COMPACT_RTF = YES +RTF_HYPERLINKS = YES +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = NO +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = NO +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +MSCGEN_PATH = /Volumes/Ragna-Blade/Applications/Doxygen/Doxygen.app/Contents/Resources/ +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/kim/html/doxygen.css b/doc/kim/html/doxygen.css new file mode 100644 index 0000000000..c7db1a8a04 --- /dev/null +++ b/doc/kim/html/doxygen.css @@ -0,0 +1,358 @@ +BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Geneva, Arial, Helvetica, sans-serif; +} +BODY,TD { + font-size: 90%; +} +H1 { + text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; +} +CAPTION { font-weight: bold } +DIV.qindex { + width: 100%; + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; +} +DIV.nav { + width: 100%; + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; +} +DIV.navtab { + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} +TD.navtab { + font-size: 70%; +} +A.qindex { + text-decoration: none; + font-weight: bold; + color: #1A419D; +} +A.qindex:visited { + text-decoration: none; + font-weight: bold; + color: #1A419D +} +A.qindex:hover { + text-decoration: none; + background-color: #ddddff; +} +A.qindexHL { + text-decoration: none; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + border: 1px double #9295C2; +} +A.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; +} +A.qindexHL:visited { text-decoration: none; background-color: #6666cc; color: #ffffff } +A.el { text-decoration: none; font-weight: bold } +A.elRef { font-weight: bold } +A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} +A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} +A.codeRef:link { font-weight: normal; color: #0000FF} +A.codeRef:visited { font-weight: normal; color: #0000FF} +A:hover { text-decoration: none; background-color: #f2f2ff } +DL.el { margin-left: -1cm } +.fragment { + font-family: monospace, fixed; + font-size: 95%; +} +PRE.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + margin-top: 4px; + margin-bottom: 4px; + margin-left: 2px; + margin-right: 8px; + padding-left: 6px; + padding-right: 6px; + padding-top: 4px; + padding-bottom: 4px; +} +DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } + +DIV.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; +} +DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } +BODY { + background: white; + color: black; + margin-right: 20px; + margin-left: 20px; +} +TD.indexkey { + background-color: #e8eef2; + font-weight: bold; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; +} +TD.indexvalue { + background-color: #e8eef2; + font-style: italic; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; +} +TR.memlist { + background-color: #f0f0f0; +} +P.formulaDsp { text-align: center; } +IMG.formulaDsp { } +IMG.formulaInl { vertical-align: middle; } +SPAN.keyword { color: #008000 } +SPAN.keywordtype { color: #604020 } +SPAN.keywordflow { color: #e08000 } +SPAN.comment { color: #800000 } +SPAN.preprocessor { color: #806020 } +SPAN.stringliteral { color: #002080 } +SPAN.charliteral { color: #008080 } +.mdescLeft { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; +} +.mdescRight { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; +} +.memItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplParams { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + color: #606060; + background-color: #FAFAFA; + font-size: 80%; +} +.search { color: #003399; + font-weight: bold; +} +FORM.search { + margin-bottom: 0px; + margin-top: 0px; +} +INPUT.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #e8eef2; +} +TD.tiny { font-size: 75%; +} +a { + color: #1A41A8; +} +a:visited { + color: #2A3798; +} +.dirtab { padding: 4px; + border-collapse: collapse; + border: 1px solid #84b0c7; +} +TH.dirtab { background: #e8eef2; + font-weight: bold; +} +HR { height: 1px; + border: none; + border-top: 1px solid black; +} + +/* Style for detailed member documentation */ +.memtemplate { + font-size: 80%; + color: #606060; + font-weight: normal; +} +.memnav { + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} +.memitem { + padding: 4px; + background-color: #eef3f5; + border-width: 1px; + border-style: solid; + border-color: #dedeee; + -moz-border-radius: 8px 8px 8px 8px; +} +.memname { + white-space: nowrap; + font-weight: bold; +} +.memdoc{ + padding-left: 10px; +} +.memproto { + background-color: #d5e1e8; + width: 100%; + border-width: 1px; + border-style: solid; + border-color: #84b0c7; + font-weight: bold; + -moz-border-radius: 8px 8px 8px 8px; +} +.paramkey { + text-align: right; +} +.paramtype { + white-space: nowrap; +} +.paramname { + color: #602020; + font-style: italic; + white-space: nowrap; +} +/* End Styling for detailed member documentation */ + +/* for the tree view */ +.ftvtree { + font-family: sans-serif; + margin:0.5em; +} +.directory { font-size: 9pt; font-weight: bold; } +.directory h3 { margin: 0px; margin-top: 1em; font-size: 11pt; } +.directory > h3 { margin-top: 0; } +.directory p { margin: 0px; white-space: nowrap; } +.directory div { display: none; margin: 0px; } +.directory img { vertical-align: -30%; } diff --git a/doc/kim/html/doxygen.png b/doc/kim/html/doxygen.png new file mode 100644 index 0000000000..f0a274bbaf Binary files /dev/null and b/doc/kim/html/doxygen.png differ diff --git a/doc/kim/html/group__kim__ccache__iterator__reference.html b/doc/kim/html/group__kim__ccache__iterator__reference.html new file mode 100644 index 0000000000..7f7144f76c --- /dev/null +++ b/doc/kim/html/group__kim__ccache__iterator__reference.html @@ -0,0 +1,114 @@ + + +Kerberos Identity Management: KIM CCache Iterator Reference Documentation + + + + +

KIM CCache Iterator Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + +
kim_error_t kim_ccache_iterator_create (kim_ccache_iterator_t *  out_ccache_iterator  ) 
+
+
+ +

+Get a ccache iterator to enumerate ccaches in the cache collection. +

+

Parameters:
+ + +
out_ccache_iterator on exit, a ccache iterator object for the cache collection.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_iterator_next (kim_ccache_iterator_t  in_ccache_iterator,
kim_ccache_t *  out_ccache 
)
+
+
+ +

+Get the next ccache in the cache collection. +

+

Parameters:
+ + + +
in_ccache_iterator a ccache iterator object.
out_ccache on exit, the next ccache in the cache collection. If there are no more ccaches in the cache collection this argument will be set to NULL.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_ccache_iterator_free (kim_ccache_iterator_t *  io_ccache_iterator  ) 
+
+
+ +

+Free memory associated with a ccache iterator. +

+

Parameters:
+ + +
io_ccache_iterator a ccache iterator object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__ccache__reference.html b/doc/kim/html/group__kim__ccache__reference.html new file mode 100644 index 0000000000..85dfa9c4c1 --- /dev/null +++ b/doc/kim/html/group__kim__ccache__reference.html @@ -0,0 +1,944 @@ + + +Kerberos Identity Management: KIM CCache Reference Documentation + + + + +

KIM CCache Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_new (kim_ccache_t *  out_ccache,
kim_identity_t  in_client_identity,
kim_options_t  in_options 
)
+
+
+ +

+Acquire a new initial credential and store it in a ccache. +

+

Parameters:
+ + + + +
out_ccache on exit, a new cache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to allow the user to choose.
in_options options to control credential acquisition.
+
+
Note:
Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_new_if_needed (kim_ccache_t *  out_ccache,
kim_identity_t  in_client_identity,
kim_options_t  in_options 
)
+
+
+ +

+Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential. +

+

Parameters:
+ + + + +
out_ccache on exit, a ccache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
in_client_identity a client identity to obtain a credential for.
in_options options to control credential acquisition (if a credential is acquired).
+
+
Note:
Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_from_client_identity (kim_ccache_t *  out_ccache,
kim_identity_t  in_client_identity 
)
+
+
+ +

+Find a ccache for a client identity in the cache collection. +

+

Parameters:
+ + + +
out_ccache on exit, a ccache object for a ccache containing a TGT credential. Must be freed with kim_ccache_free().
in_client_identity a client identity to obtain a credential for.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_from_keytab (kim_ccache_t *  out_ccache,
kim_identity_t  in_identity,
kim_options_t  in_options,
kim_string_t  in_keytab 
)
+
+
+ +

+Acquire a new initial credential from a keytab and store it in a ccache. +

+

Parameters:
+ + + + + +
out_ccache on exit, a new ccache object containing an initial credential for the client identity in_identity obtained using in_keytab. Must be freed with kim_ccache_free().
in_identity a client identity to obtain a credential for. Specify NULL for the first client identity in the keytab.
in_options options to control credential acquisition.
in_keytab a path to a keytab. Specify NULL for the default keytab location.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_ccache_create_from_default (kim_ccache_t *  out_ccache  ) 
+
+
+ +

+Get the default ccache. +

+

Parameters:
+ + +
out_ccache on exit, a ccache object for the default ccache. Must be freed with kim_ccache_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_from_type_and_name (kim_ccache_t *  out_ccache,
kim_string_t  in_type,
kim_string_t  in_name 
)
+
+
+ +

+Get a ccache for a ccache type and name. +

+

Parameters:
+ + + + +
out_ccache on exit, a ccache object for the ccache identified by in_type and in_name. Must be freed with kim_ccache_free().
in_type a ccache type string.
in_name a ccache name string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_create_from_krb5_ccache (kim_ccache_t *  out_ccache,
krb5_context  in_krb5_context,
krb5_ccache  in_krb5_ccache 
)
+
+
+ +

+Get a ccache for a krb5 ccache. +

+

Parameters:
+ + + + +
out_ccache on exit, a new ccache object which is a copy of in_krb5_ccache. Must be freed with kim_ccache_free().
in_krb5_context the krb5 context used to create in_krb5_ccache.
in_krb5_ccache a krb5 ccache object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_copy (kim_ccache_t *  out_ccache,
kim_ccache_t  in_ccache 
)
+
+
+ +

+Copy a ccache. +

+

Parameters:
+ + + +
out_ccache on exit, the new ccache object which is a copy of in_ccache. Must be freed with kim_ccache_free().
in_ccache a ccache object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_krb5_ccache (kim_ccache_t  in_ccache,
krb5_context  in_krb5_context,
krb5_ccache *  out_krb5_ccache 
)
+
+
+ +

+Get a krb5 ccache for a ccache. +

+

Parameters:
+ + + + +
in_ccache a ccache object.
in_krb5_context a krb5 context which will be used to create out_krb5_ccache.
out_krb5_ccache on exit, a new krb5 ccache object which is a copy of in_ccache. Must be freed with krb5_cc_close() or krb5_cc_destroy().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_name (kim_ccache_t  in_ccache,
kim_string_t *  out_name 
)
+
+
+ +

+Get the name of a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_name on exit, the name string of in_ccache.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_type (kim_ccache_t  in_ccache,
kim_string_t *  out_type 
)
+
+
+ +

+Get the type of a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_type on exit, the type string of in_ccache.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_display_name (kim_ccache_t  in_ccache,
kim_string_t *  out_display_name 
)
+
+
+ +

+Get the type and name for a ccache in display format. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_display_name on exit, the type and name of in_ccache in a format appropriate for display to the user in command line programs. (ie: "<type>:<name>") Must be freed with kim_string_free(). Note: this string can also be passed to krb5_cc_resolve().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_client_identity (kim_ccache_t  in_ccache,
kim_identity_t *  out_client_identity 
)
+
+
+ +

+Get the client identity for a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_client_identity on exit, an identity object containing the client identity of in_ccache. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_valid_credential (kim_ccache_t  in_ccache,
kim_credential_t *  out_credential 
)
+
+
+ +

+Get the first valid credential in a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_credential on exit, the first valid credential in in_ccache. Must be freed with kim_credential_free(). Set to NULL if you only want return value, not the actual credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This function prefers TGT credentials. If there are any non-valid TGTs in the ccache, it will always return an error. However, if there are no TGTs at all, it will return the first valid non-TGT credential. If you only want TGTs, use kim_credential_is_tgt() to verify that out_credential is a tgt.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_start_time (kim_ccache_t  in_ccache,
kim_time_t *  out_start_time 
)
+
+
+ +

+Get the time when the credentials in the ccache become valid. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_start_time on exit, the time when the credentials in in_ccache become valid. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_expiration_time (kim_ccache_t  in_ccache,
kim_time_t *  out_expiration_time 
)
+
+
+ +

+Get the time when the credentials in the ccache will expire. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_expiration_time on exit, the time when the credentials in in_ccache will expire. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_get_renewal_expiration_time (kim_ccache_t  in_ccache,
kim_time_t *  out_renewal_expiration_time 
)
+
+
+ +

+Get the time when the credentials in the ccache will no longer be renewable. +

+

Parameters:
+ + + +
in_ccache a ccache object.
out_renewal_expiration_time on exit, the time when the credentials in in_ccache will no longer be renewable. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_ccache_set_default (kim_ccache_t  io_ccache  ) 
+
+
+ +

+Set a ccache to the default ccache. +

+

Parameters:
+ + +
io_ccache a ccache object which will be set to the default ccache.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_verify (kim_ccache_t  in_ccache,
kim_identity_t  in_service_identity,
kim_string_t  in_keytab,
kim_boolean_t  in_fail_if_no_service_key 
)
+
+
+ +

+Verify the TGT in a ccache. +

+

Parameters:
+ + + + + +
in_ccache a ccache object containing the TGT credential to be verified.
in_service_identity a service identity to look for in the keytab. Specify KIM_IDENTITY_ANY to use the default service identity (usually host/<host's FQDN><host's local realm>).
in_keytab a path to a keytab. Specify NULL for the default keytab location.
in_fail_if_no_service_key whether or not the absence of a key for in_service_identity in the host's keytab will cause a failure.
+
+
Note:
specifying FALSE for in_fail_if_no_service_key may expose the calling program to the Zanarotti attack if the host has no keytab installed.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_renew (kim_ccache_t  in_ccache,
kim_options_t  in_options 
)
+
+
+ +

+Renew the TGT in a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object containing a TGT to be renewed.
in_options initial credential options to be used if a new credential is obtained.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_ccache_validate (kim_ccache_t  in_ccache,
kim_options_t  in_options 
)
+
+
+ +

+Validate the TGT in a ccache. +

+

Parameters:
+ + + +
in_ccache a ccache object containing a TGT to be validated.
in_options initial credential options.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_ccache_destroy (kim_ccache_t *  io_ccache  ) 
+
+
+ +

+Remove a ccache from the cache collection. +

+

Parameters:
+ + +
io_ccache a ccache object to be destroyed. Set to NULL on exit.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
Frees memory associated with the ccache. Do not call kim_ccache_free() after calling this function.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_ccache_free (kim_ccache_t *  io_ccache  ) 
+
+
+ +

+Free memory associated with a ccache. +

+

Parameters:
+ + +
io_ccache a ccache object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__credential__iterator__reference.html b/doc/kim/html/group__kim__credential__iterator__reference.html new file mode 100644 index 0000000000..f1ffa68bd8 --- /dev/null +++ b/doc/kim/html/group__kim__credential__iterator__reference.html @@ -0,0 +1,124 @@ + + +Kerberos Identity Management: KIM Credential Iterator Reference Documentation + + + + +

KIM Credential Iterator Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_iterator_create (kim_credential_iterator_t *  out_credential_iterator,
kim_ccache_t  in_ccache 
)
+
+
+ +

+Get a credential iterator to enumerate credentials in a ccache. +

+

Parameters:
+ + + +
out_credential_iterator on exit, a credential iterator object for in_ccache. Must be freed with kim_credential_iterator_free().
in_ccache a ccache object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_iterator_next (kim_credential_iterator_t  in_credential_iterator,
kim_credential_t *  out_credential 
)
+
+
+ +

+Get the next credential in a ccache. +

+

Parameters:
+ + + +
in_credential_iterator a credential iterator object.
out_credential on exit, the next credential in the ccache iterated by in_credential_iterator. Must be freed with kim_credential_free(). If there are no more credentials this argument will be set to NULL.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_credential_iterator_free (kim_credential_iterator_t *  io_credential_iterator  ) 
+
+
+ +

+Free memory associated with a credential iterator. +

+

Parameters:
+ + +
io_credential_iterator a credential iterator object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__credential__reference.html b/doc/kim/html/group__kim__credential__reference.html new file mode 100644 index 0000000000..290e1a4042 --- /dev/null +++ b/doc/kim/html/group__kim__credential__reference.html @@ -0,0 +1,736 @@ + + +Kerberos Identity Management: KIM Credential Reference Documentation + + + + +

KIM Credential Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_create_new (kim_credential_t *  out_credential,
kim_identity_t  in_client_identity,
kim_options_t  in_options 
)
+
+
+ +

+Acquire a new initial credential. +

+

Parameters:
+ + + + +
out_credential on exit, a new credential object containing a newly acquired initial credential. Must be freed with kim_credential_free().
in_client_identity a client identity to obtain a credential for. Specify NULL to allow the user to choose the identity
in_options options to control credential acquisition.
+
+
Note:
Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_create_new
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_create_from_keytab (kim_credential_t *  out_credential,
kim_identity_t  in_identity,
kim_options_t  in_options,
kim_string_t  in_keytab 
)
+
+
+ +

+Acquire a new initial credential from a keytab. +

+

Parameters:
+ + + + + +
out_credential on exit, a new credential object containing an initial credential for in_identity obtained using in_keytab. Must be freed with kim_credential_free().
in_identity a client identity to obtain a credential for. Specify NULL for the first identity in the keytab.
in_options options to control credential acquisition.
in_keytab a path to a keytab. Specify NULL for the default keytab location.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_create_from_keytab
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_create_from_krb5_creds (kim_credential_t *  out_credential,
krb5_context  in_krb5_context,
krb5_creds *  in_krb5_creds 
)
+
+
+ +

+Copy a credential from a krb5 credential object. +

+

Parameters:
+ + + + +
out_credential on exit, a new credential object which is a copy of in_krb5_creds. Must be freed with kim_credential_free().
in_krb5_context the krb5 context used to create in_krb5_creds.
in_krb5_creds a krb5 credential object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_copy (kim_credential_t *  out_credential,
kim_credential_t  in_credential 
)
+
+
+ +

+Copy a credential object. +

+

Parameters:
+ + + +
out_credential on exit, a new credential object which is a copy of in_credential. Must be freed with kim_credential_free().
in_credential a credential object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_krb5_creds (kim_credential_t  in_credential,
krb5_context  in_krb5_context,
krb5_creds **  out_krb5_creds 
)
+
+
+ +

+Get a krb5 credentials object for a credential object. +

+

Parameters:
+ + + + +
in_credential a credential object.
in_krb5_context a krb5 context which will be used to create out_krb5_creds.
out_krb5_creds on exit, a new krb5 creds object which is a copy of in_credential. Must be freed with krb5_free_creds().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_client_identity (kim_credential_t  in_credential,
kim_identity_t *  out_client_identity 
)
+
+
+ +

+Get the client identity of a credential object. +

+

Parameters:
+ + + +
in_credential a credential object.
out_client_identity on exit, an identity object containing the client identity of in_credential. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_service_identity (kim_credential_t  in_credential,
kim_identity_t *  out_service_identity 
)
+
+
+ +

+Get the service identity of a credential object. +

+

Parameters:
+ + + +
in_credential a credential object.
out_service_identity on exit, an identity object containing the service identity of in_credential. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_is_tgt (kim_credential_t  in_credential,
kim_boolean_t *  out_is_tgt 
)
+
+
+ +

+Check if a credential is a ticket granting ticket. +

+

Parameters:
+ + + +
in_credential a credential object.
out_is_tgt on exit, whether or not the credential is a TGT.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_state (kim_credential_t  in_credential,
kim_credential_state_t *  out_state 
)
+
+
+ +

+Check the state of a credential (valid, expired, postdated, etc). +

+

Parameters:
+ + + +
in_credential a credential object.
out_state on exit, the state of the credential. See kim_credential_state_enum for the possible values of out_state.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_start_time (kim_credential_t  in_credential,
kim_time_t *  out_start_time 
)
+
+
+ +

+Get the time when the credentials become valid. +

+

Parameters:
+ + + +
in_credential a credential object.
out_start_time on exit, the time when in_credential becomes valid. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_get_start_time
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_expiration_time (kim_credential_t  in_credential,
kim_time_t *  out_expiration_time 
)
+
+
+ +

+Get the time when the credentials will expire. +

+

Parameters:
+ + + +
in_credential a credential object.
out_expiration_time on exit, the time when in_credential will expire. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_get_expiration_time
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_get_renewal_expiration_time (kim_credential_t  in_credential,
kim_time_t *  out_renewal_expiration_time 
)
+
+
+ +

+Get the time when the credentials will no longer be renewable. +

+

Parameters:
+ + + +
in_credential a credential object.
out_renewal_expiration_time on exit, the time when in_credential will no longer be renewable. May be in the past or future.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_get_renewal_expiration_time
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_store (kim_credential_t  in_credential,
kim_identity_t  in_client_identity,
kim_ccache_t *  out_ccache 
)
+
+
+ +

+Store a credential in a ccache in the cache collection. +

+

Parameters:
+ + + + +
in_credential a credential object.
in_client_identity a client identity.
out_ccache on exit, a ccache object containing in_credential with the client identity in_client_identity. Must be freed with kim_ccache_free(). Specify NULL if you don't want this return value.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_verify (kim_credential_t  in_credential,
kim_identity_t  in_service_identity,
kim_string_t  in_keytab,
kim_boolean_t  in_fail_if_no_service_key 
)
+
+
+ +

+Verify a TGT credential. +

+

Parameters:
+ + + + + +
in_credential a TGT credential to be verified.
in_service_identity a service identity to look for in the keytab. Specify KIM_IDENTITY_ANY to use the default service identity (usually host/<host's FQDN><host's local realm>).
in_keytab a path to a keytab. Specify NULL for the default keytab location.
in_fail_if_no_service_key whether or not the absence of a key for in_service_identity in the host's keytab will cause a failure.
+
+
Note:
specifying FALSE for in_fail_if_no_service_key may expose the calling program to the Zanarotti attack if the host has no keytab installed.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_verify
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_renew (kim_credential_t *  io_credential,
kim_options_t  in_options 
)
+
+
+ +

+Renew a TGT credential. +

+

Parameters:
+ + + +
io_credential a TGT credential to be renewed. On exit, the old credential object will be freed and io_credential will be replaced with a new renewed credential. The new credential must be freed with kim_credential_free().
in_options initial credential options.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_renew
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_credential_validate (kim_credential_t *  io_credential,
kim_options_t  in_options 
)
+
+
+ +

+Validate a TGT credential. +

+

Parameters:
+ + + +
io_credential a credential object to be validated. On exit, the old credential object will be freed and io_credential will be replaced with a new validated credential. The new credential must be freed with kim_credential_free().
in_options initial credential options.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_ccache_validate
+ +
+

+ +

+
+ + + + + + + + + +
void kim_credential_free (kim_credential_t *  io_credential  ) 
+
+
+ +

+Free memory associated with a credential object. +

+

Parameters:
+ + +
io_credential the credential object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__error__reference.html b/doc/kim/html/group__kim__error__reference.html new file mode 100644 index 0000000000..0eca34a03b --- /dev/null +++ b/doc/kim/html/group__kim__error__reference.html @@ -0,0 +1,143 @@ + + +Kerberos Identity Management: KIM Error Reference Documentation + + + + +

KIM Error Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_error_copy (kim_error_t *  out_error,
kim_error_t  in_error 
)
+
+
+ +

+Copy an error. +

+

Parameters:
+ + + +
out_error on exit, a new error object which is a copy of in_error. Must be freed with kim_error_free().
in_error the error to copy.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_code_t kim_error_get_code (kim_error_t  in_error  ) 
+
+
+ +

+Get a numerical error code for an error. +

+

Parameters:
+ + +
in_error an error object.
+
+
Returns:
On success, a machine-readable error code describing the error represented by in_error. On failure, KIM_PARAMETER_ECODE.
+ +
+

+ +

+
+ + + + + + + + + +
kim_string_t kim_error_get_display_string (kim_error_t  in_error  ) 
+
+
+ +

+Get a text description of an error. +

+

Parameters:
+ + +
in_error an error object.
+
+
Returns:
On success, a human-readable error string describing the error represented by in_error. On failure, NULL, indicating that the kim_error_t object was invalid.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_error_free (kim_error_t *  io_error  ) 
+
+
+ +

+Free memory associated with an error. +

+

Parameters:
+ + +
io_error the error object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__favorite__identities__reference.html b/doc/kim/html/group__kim__favorite__identities__reference.html new file mode 100644 index 0000000000..cf80ba42d1 --- /dev/null +++ b/doc/kim/html/group__kim__favorite__identities__reference.html @@ -0,0 +1,306 @@ + + +Kerberos Identity Management: KIM Favorite Identities Documentation + + + + +

KIM Favorite Identities Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + +
kim_error_t kim_favorite_identities_create (kim_favorite_identities_t *  out_favorite_identities  ) 
+
+
+ +

+Create a new favorite identities list. +

+

Parameters:
+ + +
out_favorite_identities on exit, a new favorite identities object. Must be freed with kim_favorite_identities_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_favorite_identities_copy (kim_favorite_identities_t *  out_favorite_identities,
kim_favorite_identities_t  in_favorite_identities 
)
+
+
+ +

+Copy a favorite identities list. +

+

Parameters:
+ + + +
out_favorite_identities on exit, a new favorite identities object which is a copy of in_favorite_identities. Must be freed with kim_favorite_identities_free().
in_favorite_identities a favorite identities object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_favorite_identities_get_number_of_identities (kim_favorite_identities_t  in_favorite_identities,
kim_count_t *  out_number_of_identities 
)
+
+
+ +

+Get the number of identities in a favorite identities list. +

+

Parameters:
+ + + +
in_favorite_identities a favorite identities object.
out_number_of_identities on exit, the number of identities in in_favorite_identities.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_favorite_identities_get_identity_at_index (kim_favorite_identities_t  in_favorite_identities,
kim_count_t  in_index,
kim_identity_t *  out_identity 
)
+
+
+ +

+Get the Nth identity in a favorite identities list. +

+

Parameters:
+ + + + +
in_favorite_identities a favorite identities object.
in_index a index into the identities list (starting at 0).
out_realm on exit, the identity at in_index in in_favorite_identities. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_favorite_identities_add_identity (kim_favorite_identities_t  io_favorite_identities,
kim_identity_t  in_identity 
)
+
+
+ +

+Add an identity to a favorite identities list. +

+

Parameters:
+ + + +
io_favorite_identities a favorite identities object.
in_identity an identity string to add to in_favorite_identities.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_favorite_identities_remove_identity (kim_favorite_identities_t  io_favorite_identities,
kim_identity_t  in_identity 
)
+
+
+ +

+Remove an identity from a identities list. +

+

Parameters:
+ + + +
io_favorite_identities a favorite identities object.
in_identity an identity to remove from in_favorite_identities.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_favorite_identities_remove_all_identities (kim_favorite_identities_t  io_favorite_identities  ) 
+
+
+ +

+Empty a favorite identities list. +

+

Parameters:
+ + +
io_favorite_identities a favorite identities object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_favorite_identities_free (kim_favorite_identities_t *  io_favorite_identities  ) 
+
+
+ +

+Free memory associated with an identities list. +

+

Parameters:
+ + +
io_favorite_identities the favorite identities object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__identity__reference.html b/doc/kim/html/group__kim__identity__reference.html new file mode 100644 index 0000000000..86d6df71f2 --- /dev/null +++ b/doc/kim/html/group__kim__identity__reference.html @@ -0,0 +1,646 @@ + + +Kerberos Identity Management: KIM Identity Reference Documentation + + + + +

KIM Identity Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_create_from_string (kim_identity_t *  out_identity,
kim_string_t  in_string 
)
+
+
+ +

+Create a identity from a string. +

+

Parameters:
+ + + +
out_identity on exit, a new identity object. Must be freed with kim_identity_free().
in_string a string representation of a Kerberos identity. Special characters such as '/' and '@' must be escaped with '\'.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_create_from_components (kim_identity_t *  out_identity,
kim_string_t  in_realm,
kim_string_t  in_1st_component,
  ... 
)
+
+
+ +

+Create a identity from a realm and component strings. +

+

Parameters:
+ + + + + +
out_identity on exit, a new identity object. Must be freed with kim_identity_free().
in_realm a string representation of a Kerberos realm.
in_1st_component a string representing the first component of the identity.
... zero or more strings of type kim_string_t representing additional components of the identity followed by a terminating NULL. Components will be assembled in order (ie: the 4th argument to kim_identity_create_from_components() will be the 2nd component of the identity).
+
+
Note:
The last argument must be a NULL or kim_identity_create_from_components() may crash.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_create_from_krb5_principal (kim_identity_t *  out_identity,
krb5_context  in_krb5_context,
krb5_principal  in_krb5_principal 
)
+
+
+ +

+Create an identity object from a krb5_principal. +

+

Parameters:
+ + + + +
out_identity on exit, a new identity object which is a copy of in_krb5_principal. Must be freed with kim_identity_free().
in_krb5_context the krb5 context used to create in_krb5_principal.
in_krb5_principal a krb5 principal object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_copy (kim_identity_t *  out_identity,
kim_identity_t  in_identity 
)
+
+
+ +

+Copy an identity object. +

+

Parameters:
+ + + +
out_identity on exit, a new identity object which is a copy of in_identity. Must be freed with kim_identity_free().
in_identity an identity object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_compare (kim_identity_t  in_identity,
kim_identity_t  in_compare_to_identity,
kim_comparison_t *  out_comparison 
)
+
+
+ +

+Compare identity objects for equivalency. +

+

Parameters:
+ + + + +
in_identity an identity object.
in_compare_to_identity an identity object.
out_comparison on exit, a comparison of in_identity and in_compare_to_identity which determines whether or not the two identities are equivalent and their sort order (for display to the user) if they are not.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_string (kim_identity_t  in_identity,
kim_string_t *  out_string 
)
+
+
+ +

+Get the string representation of a identity. +

+

Parameters:
+ + + +
in_identity an identity object.
out_string on exit, a string representation of in_identity. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
Special characters such as '@' and '/' will be escaped with '\'.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_display_string (kim_identity_t  in_identity,
kim_string_t *  out_display_string 
)
+
+
+ +

+Get a human-readable string representation of an identity. +

+

Parameters:
+ + + +
in_identity an identity object.
out_display_string on exit, a string representation of in_identity appropriate for display to the user. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
Special characters such as '/' and '@' are not escaped with '\'. As a result the string returned from this function cannot be used with kim_identity_create_from_string() because it does not uniquely specify a principal. The result of this function should only be used to display to the user.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_realm (kim_identity_t  in_identity,
kim_string_t *  out_realm_string 
)
+
+
+ +

+Get the realm string of an identity. +

+

Parameters:
+ + + +
in_identity an identity object.
out_realm_string on exit, a string representation of in_identity's realm. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_number_of_components (kim_identity_t  in_identity,
kim_count_t *  out_number_of_components 
)
+
+
+ +

+Get the number of components of an identity. +

+

Parameters:
+ + + +
in_identity an identity object.
out_number_of_components on exit the number of components in in_identity.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_component_at_index (kim_identity_t  in_identity,
kim_count_t  in_index,
kim_string_t *  out_component_string 
)
+
+
+ +

+Get the Nth component of an identity. +

+

Parameters:
+ + + + +
in_identity an identity object.
in_index the index of the desired component. Component indexes start at 0.
out_component_string on exit, a string representation of the component in in_identity specified by in_index. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_krb5_principal (kim_identity_t  in_identity,
krb5_context  in_krb5_context,
krb5_principal *  out_krb5_principal 
)
+
+
+ +

+Get the krb5_principal representation of an identity. +

+

Parameters:
+ + + + +
in_identity an identity object.
in_krb5_context a krb5 context object.
out_krb5_principal on exit, a krb5_principal representation of in_identity allocated with in_krb5_context. Must be freed with krb5_free_principal() using in_krb5_context.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_get_gss_name (kim_identity_t  in_identity,
gss_name_t *  out_gss_name 
)
+
+
+ +

+Get the gss_name_t representation of an identity. +

+

Parameters:
+ + + +
in_identity an identity object.
out_gss_name on exit, a gss_name_t representation of in_identity. Must be freed with gss_release_name().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_change_password (kim_identity_t  in_identity,
kim_options_t  in_options 
)
+
+
+ +

+Change the password for an identity. +

+

Parameters:
+ + + +
in_identity an identity object whose password will be changed.
in_options initial credential options to be used if a new credential is obtained.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
kim_identity_change_password() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_identity_change_password_to_password (kim_identity_t  in_identity,
kim_options_t  in_options,
kim_string_t  in_new_password 
)
+
+
+ +

+Change the password for an identity to a caller-provided new password. +

+

Parameters:
+ + + + +
in_identity an identity object whose password will be changed.
in_options initial credential options to be used if a new credential is obtained.
in_new_password a string representation of the identity's new password.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
kim_identity_change_password_with_passwords() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_identity_free (kim_identity_t *  io_identity  ) 
+
+
+ +

+Free memory associated with an identity. +

+

Parameters:
+ + +
io_identity the identity object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__options__reference.html b/doc/kim/html/group__kim__options__reference.html new file mode 100644 index 0000000000..0ab05b8329 --- /dev/null +++ b/doc/kim/html/group__kim__options__reference.html @@ -0,0 +1,1040 @@ + + +Kerberos Identity Management: KIM Options Reference Documentation + + + + +

KIM Options Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + +
kim_error_t kim_options_create (kim_options_t *  out_options  ) 
+
+
+ +

+Create new options with default values. +

+

Parameters:
+ + +
out_options on exit, a new options object. Must be freed with kim_options_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_copy (kim_options_t *  out_options,
kim_options_t  in_options 
)
+
+
+ +

+Copy options. +

+

Parameters:
+ + + +
out_options on exit, a new options object which is a copy of in_options. Must be freed with kim_options_free().
in_options a options object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_prompt_callback (kim_options_t  io_options,
kim_prompt_callback_t  in_prompt_callback 
)
+
+
+ +

+Set the prompt callback for obtaining information from the user. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_prompt_callback a prompt callback function.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
kim_prompt_callback_default
+
See also:
kim_options_get_prompt_callback()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_prompt_callback (kim_options_t  in_options,
kim_prompt_callback_t *  out_prompt_callback 
)
+
+
+ +

+Get the prompt callback for obtaining information from the user. +

+

Parameters:
+ + + +
in_options an options object.
out_prompt_callback on exit, the prompt callback specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
kim_prompt_callback_default
+
See also:
kim_options_set_prompt_callback()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_data (kim_options_t  io_options,
const void *  in_data 
)
+
+
+ +

+Set caller-specific data for use in library callbacks. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_data a pointer to caller-specific data.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
+
Default value
NULL (no data is set by default)
+
See also:
kim_options_get_data()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_data (kim_options_t  in_options,
const void **  out_data 
)
+
+
+ +

+Get caller-specific data for use in library callbacks. +

+

Parameters:
+ + + +
in_options an options object.
out_data on exit, the pointer to caller specific data specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
+
Default value
NULL (no data is set by default)
+
See also:
kim_options_set_data()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_prompt_response (kim_options_t  io_options,
kim_prompt_type_t  in_prompt_type,
void *  in_response 
)
+
+
+ +

+Set a response for a prompt for use when acquiring credentials. +

+

Parameters:
+ + + + +
io_options an options object to modify.
in_prompt_type a type of prompt.
in_response a response to prompts of in_prompt_type.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
+
Default value
NULL (no response is set by default)
+
See also:
kim_options_get_prompt_response()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_prompt_response (kim_options_t  in_options,
kim_prompt_type_t  in_prompt_type,
void **  out_response 
)
+
+
+ +

+Get the response for a prompt for use when acquiring credentials. +

+

Parameters:
+ + + + +
in_options an options object.
in_prompt_type a type of prompt.
out_response on exit, the response to prompts of type in_prompt_type specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
+
Default value
NULL (no response is set by default)
+
See also:
kim_options_set_prompt_response()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_start_time (kim_options_t  io_options,
kim_time_t  in_start_time 
)
+
+
+ +

+Set the date when a credential should become valid. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_start_time a start date (in seconds since January 1, 1970). Set to KIM_OPTIONS_START_IMMEDIATELY for the acquired credential to be valid immediately.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
When using a start time in the future, once the start time has been reached the credential must be validated before it can be used.
+
Default value
0, indicating "now". The credential will be valid immediately.
+
See also:
kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_start_time (kim_options_t  in_options,
kim_time_t *  out_start_time 
)
+
+
+ +

+Get the date when a credential should become valid. +

+

Parameters:
+ + + +
in_options an options object.
out_start_time on exit, the start date (in seconds since January 1, 1970) specified by in_options. KIM_OPTIONS_START_IMMEDIATELY indicates the credential will be valid immediately.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
When using a start time in the future, once the start time has been reached the credential must be validated before it can be used.
+
Default value
0, indicating "now". The credential will be valid immediately.
+
See also:
kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_lifetime (kim_options_t  io_options,
kim_lifetime_t  in_lifetime 
)
+
+
+ +

+Set the duration during which a credential should be valid. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_lifetime a lifetime duration (in seconds).
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
+
See also:
kim_options_get_lifetime()
+
Default value
Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_lifetime (kim_options_t  in_options,
kim_lifetime_t *  out_lifetime 
)
+
+
+ +

+Get the duration during which an acquired credential should be valid. +

+

Parameters:
+ + + +
in_options an options object.
out_lifetime on exit, the lifetime duration (in seconds) specified in in_options.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
+
Default value
Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
+
See also:
kim_options_set_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_renewable (kim_options_t  io_options,
kim_boolean_t  in_renewable 
)
+
+
+ +

+Set whether or not to request a renewable credential. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_renewable a boolean value indicating whether or not to request a renewable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_get_renewable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_renewable (kim_options_t  in_options,
kim_boolean_t *  out_renewable 
)
+
+
+ +

+Get whether or not to request a renewable credential. +

+

Parameters:
+ + + +
in_options an options object.
out_renewable on exit, a boolean value indicating whether or in_options will request a renewable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_set_renewable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_renewal_lifetime (kim_options_t  io_options,
kim_lifetime_t  in_renewal_lifetime 
)
+
+
+ +

+Set the duration during which a valid credential should be renewable. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_renewal_lifetime a renewal lifetime duration (in seconds).
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
KDCs have a maximum allowed renewal lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
+
Default value
Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
+
See also:
kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_renewal_lifetime (kim_options_t  in_options,
kim_lifetime_t *  out_renewal_lifetime 
)
+
+
+ +

+Get the duration during which a valid credential should be renewable. +

+

Parameters:
+ + + +
in_options an options object.
out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified in in_options.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
+
Default value
Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
+
See also:
kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_forwardable (kim_options_t  io_options,
kim_boolean_t  in_forwardable 
)
+
+
+ +

+Set whether or not to request a forwardable credential. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_forwardable a boolean value indicating whether or not to request a forwardable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_get_forwardable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_forwardable (kim_options_t  in_options,
kim_boolean_t *  out_forwardable 
)
+
+
+ +

+Get whether or not to request a forwardable credential. +

+

Parameters:
+ + + +
in_options an options object.
out_forwardable on exit, a boolean value indicating whether or in_options will request a forwardable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_set_forwardable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_proxiable (kim_options_t  io_options,
kim_boolean_t  in_proxiable 
)
+
+
+ +

+Set whether or not to request a proxiable credential. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_proxiable a boolean value indicating whether or not to request a proxiable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_get_proxiable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_proxiable (kim_options_t  in_options,
kim_boolean_t *  out_proxiable 
)
+
+
+ +

+Get whether or not to request a proxiable credential. +

+

Parameters:
+ + + +
in_options an options object.
out_proxiable on exit, a boolean value indicating whether or in_options will request a proxiable credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_set_proxiable()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_addressless (kim_options_t  io_options,
kim_boolean_t  in_addressless 
)
+
+
+ +

+Set whether or not to request an addressless credential. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_addressless a boolean value indicating whether or not to request an addressless credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_get_addressless()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_addressless (kim_options_t  in_options,
kim_boolean_t *  out_addressless 
)
+
+
+ +

+Get whether or not to request an addressless credential. +

+

Parameters:
+ + + +
in_options an options object.
out_addressless on exit, a boolean value indicating whether or in_options will request an addressless credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+
See also:
kim_options_set_addressless()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_set_service_name (kim_options_t  io_options,
kim_string_t  in_service_name 
)
+
+
+ +

+Set the service name to request a credential for. +

+

Parameters:
+ + + +
io_options an options object to modify.
in_service_name a service name.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
+
See also:
kim_options_get_service_name()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_options_get_service_name (kim_options_t  in_options,
kim_string_t *  out_service_name 
)
+
+
+ +

+Get the service name to request a credential for. +

+

Parameters:
+ + + +
in_options an options object.
out_service_name on exit, the service name specified in in_options. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
+
See also:
kim_options_set_service_name()
+ +
+

+ +

+
+ + + + + + + + + +
void kim_options_free (kim_options_t *  io_options  ) 
+
+
+ +

+Free memory associated with an options object. +

+

Parameters:
+ + +
io_options the options object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__preferences__reference.html b/doc/kim/html/group__kim__preferences__reference.html new file mode 100644 index 0000000000..27db8f41a9 --- /dev/null +++ b/doc/kim/html/group__kim__preferences__reference.html @@ -0,0 +1,863 @@ + + +Kerberos Identity Management: KIM Preferences Documentation + + + + +

KIM Preferences Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + +
kim_error_t kim_preferences_create (kim_preferences_t *  out_preferences  ) 
+
+
+ +

+Create a new preferences object from the current user's preferences. +

+

Parameters:
+ + +
out_preferences on exit, a new preferences object. Must be freed with kim_preferences_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_copy (kim_preferences_t *  out_preferences,
kim_preferences_t  in_preferences 
)
+
+
+ +

+Copy a preferences object. +

+

Parameters:
+ + + +
out_preferences on exit, a new preferences object which is a copy of in_preferences. Must be freed with kim_preferences_free().
in_preferences a preferences object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_options (kim_preferences_t  io_preferences,
kim_options_t  in_options 
)
+
+
+ +

+Set the user's preferred options. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_options an options object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_options (kim_preferences_t  in_preferences,
kim_options_t *  out_options 
)
+
+
+ +

+Get the user's preferred options. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_options on exit, the options specified in in_preferences. Must be freed with kim_options_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_remember_options (kim_preferences_t  io_preferences,
kim_boolean_t  in_remember_options 
)
+
+
+ +

+Set whether or not to remember the last options the user used to acquire a credential. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_remember_options a boolean value indicating whether or not to remember the last options used to acquire a credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_remember_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_remember_options (kim_preferences_t  in_preferences,
kim_boolean_t *  out_remember_options 
)
+
+
+ +

+Get whether or not to remember the last options the user used to acquire a credential. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_remember_options on exit, a boolean value indicating whether or in_preferences will remember the last options used to acquire a credential.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_remember_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_client_identity (kim_preferences_t  io_preferences,
kim_identity_t  in_client_identity 
)
+
+
+ +

+Set the user's preferred client identity. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_client_identity a client identity object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_client_identity()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_client_identity (kim_preferences_t  in_preferences,
kim_identity_t *  out_client_identity 
)
+
+
+ +

+Get the user's preferred client identity. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_client_identity on exit, the client identity specified in in_preferences. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_client_identity()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_remember_client_identity (kim_preferences_t  io_preferences,
kim_boolean_t  in_remember_client_identity 
)
+
+
+ +

+Set whether or not to remember the last client identity the user acquired a credential for. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_remember_client_identity a boolean value indicating whether or not to remember the last client identity for which a credential was acquired.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_remember_client_identity()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_remember_client_identity (kim_preferences_t  in_preferences,
kim_boolean_t *  out_remember_client_identity 
)
+
+
+ +

+Get whether or not to remember the last client identity the user acquired a credential for. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_remember_client_identity on exit, a boolean value indicating whether or in_preferences will remember the last client identity for which a credential was acquired.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_remember_client_identity()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_minimum_lifetime (kim_preferences_t  io_preferences,
kim_lifetime_t  in_minimum_lifetime 
)
+
+
+ +

+Set the minimum credential lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_minimum_lifetime a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credentials.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_minimum_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_minimum_lifetime (kim_preferences_t  in_preferences,
kim_lifetime_t *  out_minimum_lifetime 
)
+
+
+ +

+Get the minimum credential lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_minimum_lifetime on exit, the minimum lifetime that GUI tools will allow the user to specify for credentials.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_minimum_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_maximum_lifetime (kim_preferences_t  io_preferences,
kim_lifetime_t  in_maximum_lifetime 
)
+
+
+ +

+Set the maximum credential lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_maximum_lifetime a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credentials.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_maximum_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_maximum_lifetime (kim_preferences_t  in_preferences,
kim_lifetime_t *  out_maximum_lifetime 
)
+
+
+ +

+Get the maximum credential lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_maximum_lifetime on exit, the maximum lifetime that GUI tools will allow the user to specify for credentials.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_maximum_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_minimum_renewal_lifetime (kim_preferences_t  io_preferences,
kim_lifetime_t  in_minimum_renewal_lifetime 
)
+
+
+ +

+Set the minimum credential renewal lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_minimum_renewal_lifetime a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credential renewal.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_minimum_renewal_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_minimum_renewal_lifetime (kim_preferences_t  in_preferences,
kim_lifetime_t *  out_minimum_renewal_lifetime 
)
+
+
+ +

+Get the minimum credential renewal lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_minimum_renewal_lifetime on exit, the minimum lifetime that GUI tools will allow the user to specify for credential renewal.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_minimum_renewal_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_maximum_renewal_lifetime (kim_preferences_t  io_preferences,
kim_lifetime_t  in_maximum_renewal_lifetime 
)
+
+
+ +

+Set the maximum credential renewal lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_maximum_renewal_lifetime a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credential renewal.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_minimum_renewal_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_maximum_renewal_lifetime (kim_preferences_t  in_preferences,
kim_lifetime_t *  out_maximum_renewal_lifetime 
)
+
+
+ +

+Get the maximum credential renewal lifetime for GUI credential lifetime controls. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_maximum_renewal_lifetime on exit, the maximum lifetime that GUI tools will allow the user to specify for credential renewal.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_minimum_renewal_lifetime()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_set_favorite_identities (kim_preferences_t  io_preferences,
kim_favorite_identities_t  in_favorite_identities 
)
+
+
+ +

+Set the user's preferred list of identities. +

+

Parameters:
+ + + +
io_preferences a preferences object to modify.
in_favorite_identities a favorite identities object. See KIM Favorite Identities Overview for more information on KIM Favorite Identities.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_get_favorite_identities()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_preferences_get_favorite_identities (kim_preferences_t  in_preferences,
kim_favorite_identities_t *  out_favorite_identities 
)
+
+
+ +

+Get the user's preferred list of identities. +

+

Parameters:
+ + + +
in_preferences a preferences object.
out_favorite_identities on exit, a copy of the favorite identities specified in in_preferences. See KIM Favorite Identities Overview for more information on KIM Favorite Identities. Must be freed with kim_favorite_identities_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_preferences_set_favorite_identities()
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_preferences_synchronize (kim_preferences_t  in_preferences  ) 
+
+
+ +

+Synchronize a preferences object with the user's preferences, writing pending changes and reading any changes applied by other processes. +

+

Parameters:
+ + +
in_preferences a preferences object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_preferences_free (kim_preferences_t *  io_preferences  ) 
+
+
+ +

+Free memory associated with a preferences object. +

+

Parameters:
+ + +
io_preferences the preferences object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__selection__hints__reference.html b/doc/kim/html/group__kim__selection__hints__reference.html new file mode 100644 index 0000000000..85d5c15ab5 --- /dev/null +++ b/doc/kim/html/group__kim__selection__hints__reference.html @@ -0,0 +1,1118 @@ + + +Kerberos Identity Management: KIM Selection Hints Reference Documentation + + + + +

KIM Selection Hints Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_create (kim_selection_hints_t *  out_selection_hints,
kim_string_t  in_application_identifier 
)
+
+
+ +

+Create a new selection hints object. +

+

Parameters:
+ + + +
out_selection_hints on exit, a new selection hints object. Must be freed with kim_selection_hints_free().
in_application_identifier an application identifier string. Java-style identifiers are recommended to avoid cache entry collisions (eg: "com.example.MyApplication")
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_copy (kim_selection_hints_t *  out_selection_hints,
kim_selection_hints_t  in_selection_hints 
)
+
+
+ +

+Copy a selection hints object. +

+

Parameters:
+ + + +
out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints. Must be freed with kim_selection_hints_free().
in_selection_hints a selection hints object.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_service_identity_hint (kim_selection_hints_t  io_selection_hints,
kim_identity_t  in_service_identity 
)
+
+
+ +

+Set the preferred service identity. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_service_identity a service identity.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_service_identity_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_service_identity_hint (kim_selection_hints_t  in_selection_hints,
kim_identity_t *  out_service_identity 
)
+
+
+ +

+Get the preferred service identity. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_service_identity on exit, the service identity specified in in_selection_hints. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_service_identity_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_client_realm_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_client_realm 
)
+
+
+ +

+Set the preferred client realm. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_client_realm a client realm string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_client_realm_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_client_realm_hint (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_client_realm 
)
+
+
+ +

+Get the preferred client realm. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_client_realm on exit, the client realm string specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_client_realm_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_user_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_user 
)
+
+
+ +

+Set the preferred user name. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_user a user name string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_user_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_user_hint (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_user 
)
+
+
+ +

+Get the preferred user name. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_user on exit, the user name string specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_user_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_service_realm_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_service_realm 
)
+
+
+ +

+Set the preferred service realm. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_service_realm a service realm string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_service_realm_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_service_realm_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t *  out_service_realm 
)
+
+
+ +

+Get the preferred service realm. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object.
out_service_realm on exit, the service realm string specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_service_realm_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_service_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_service 
)
+
+
+ +

+Set the preferred service name. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_service a service name string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_service_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_service_hint (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_service 
)
+
+
+ +

+Get the preferred service name. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_service on exit, the service name string specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_service_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_server_hint (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_server 
)
+
+
+ +

+Set the preferred server host name. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_server a server host name string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_server_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_server_hint (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_server 
)
+
+
+ +

+Get the preferred server host name. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_server on exit, the server host name string specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_server_hint()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_application_name (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_application_name 
)
+
+
+ +

+Set the application name for use in user interaction. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_application_name a localized string containing the full name of the application.
+
+
Note:
If you do not call this function KIM will attempt to determine the application name at runtime. If that fails (the functionality is only available on some platforms) then KIM will use the application identity string.
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_application_name()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_application_name (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_application_name 
)
+
+
+ +

+Get the application name for use in user interaction. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_application_name on exit, the localized full name of the application specified in in_selection_hints. Must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_application_name()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_explanation (kim_selection_hints_t  io_selection_hints,
kim_string_t  in_explanation 
)
+
+
+ +

+Set the strings used to prompt the user to select the identity. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_explanation a localized string describing why the caller needs the identity.
+
+
Note:
If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. You may still need to call kim_selection_hints_set_application_name()
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_explanation()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_explanation (kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_explanation 
)
+
+
+ +

+Get the strings used to prompt the user to select the identity. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_explanation on exit, the localized string specified in in_selection_hints which describes why the caller needs the identity. May be NULL. If non-NULL, must be freed with kim_string_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_explanation()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_options (kim_selection_hints_t  io_selection_hints,
kim_options_t  in_options 
)
+
+
+ +

+Set the options which will be used if credentials need to be acquired. +

+

Parameters:
+ + + +
io_selection_hints a selection hints object to modify.
in_options options to control credential acquisition.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_get_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_options (kim_selection_hints_t  in_selection_hints,
kim_options_t *  out_options 
)
+
+
+ +

+Get the options which will be used if credentials need to be acquired. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object.
out_options on exit, the options to control credential acquisition specified in in_selection_hints. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
See also:
kim_selection_hints_set_options()
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_allow_user_interaction (kim_selection_hints_t  in_selection_hints,
kim_boolean_t  in_allow_user_interaction 
)
+
+
+ +

+Set whether or not KIM may interact with the user to select an identity. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object to modify
in_allow_user_interaction a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This setting defaults to TRUE.
+
See also:
kim_selection_hints_get_allow_user_interaction
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_allow_user_interaction (kim_selection_hints_t  in_selection_hints,
kim_boolean_t *  out_allow_user_interaction 
)
+
+
+ +

+Get whether or not KIM may interact with the user to select an identity. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object to modify
out_allow_user_interaction on exit, a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This setting defaults to TRUE.
+
See also:
kim_selection_hints_set_allow_user_interaction
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_set_remember_identity (kim_selection_hints_t  in_selection_hints,
kim_boolean_t  in_remember_identity 
)
+
+
+ +

+Set whether or not KIM will use cached mappings for this selection hints object. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object to modify
in_remember_identity a boolean value specifying whether or not KIM should use a cached mapping between in_selection_hints and a Kerberos identity.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This setting defaults to TRUE.
+
See also:
kim_selection_hints_get_remember_identity
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_remember_identity (kim_selection_hints_t  in_selection_hints,
kim_boolean_t *  out_remember_identity 
)
+
+
+ +

+Get whether or not KIM will use cache mappings for this selection hints object. +

+

Parameters:
+ + + +
in_selection_hints a selection hints object to modify
out_remember_identity on exit, a boolean value specifying whether or not KIM will use a cached mapping between in_selection_hints and a Kerberos identity.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
This setting defaults to TRUE.
+
See also:
kim_selection_hints_set_remember_identity
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_get_identity (kim_selection_hints_t  in_selection_hints,
kim_identity_t *  out_identity 
)
+
+
+ +

+Choose a client identity based on selection hints. +

+

Parameters:
+ + + +
in_selection_hints the selection hints to add to the cache.
out_identity the Kerberos identity in_selection_hints maps to. Must be freed with kim_identity_free().
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+
Note:
out_identity is the identity mapped to by the current state of in_selection_hints. This function may prompt the user via a GUI to choose that identity. Subsequent modifications to in_selection_hints will not change out_identity.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_selection_hints_remember_identity (kim_selection_hints_t  in_selection_hints,
kim_identity_t  in_identity 
)
+
+
+ +

+Add an entry for the selection hints to the selection hints cache, replacing any existing entry. +

+

Parameters:
+ + + +
in_selection_hints the selection hints to add to the cache.
in_identity the Kerberos identity in_selection_hints maps to.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
kim_error_t kim_selection_hints_forget_identity (kim_selection_hints_t  in_selection_hints  ) 
+
+
+ +

+Remove an entry for the selection hints from the selection hints cache. +

+

Parameters:
+ + +
in_selection_hints the selection hints to remove from the cache.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_selection_hints_free (kim_selection_hints_t *  io_selection_hints  ) 
+
+
+ +

+Free memory associated with a selection hints object. +

+

Parameters:
+ + +
io_selection_hints the selection hints object to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__string__reference.html b/doc/kim/html/group__kim__string__reference.html new file mode 100644 index 0000000000..46d2251180 --- /dev/null +++ b/doc/kim/html/group__kim__string__reference.html @@ -0,0 +1,131 @@ + + +Kerberos Identity Management: KIM String Reference Documentation + + + + +

KIM String Reference Documentation

+

+

Functions

+ +

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
kim_error_t kim_string_copy (kim_string_t *  out_string,
const kim_string_t  in_string 
)
+
+
+ +

+Copy a string. +

+

Parameters:
+ + + +
out_string on exit, a new string object which is a copy of in_string. Must be freed with kim_string_free().
in_string the string to copy.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_t kim_string_compare (kim_string_t  in_string,
kim_string_t  in_compare_to_string,
kim_comparison_t *  out_comparison 
)
+
+
+ +

+Compare two strings. +

+

Parameters:
+ + + + +
in_string a string.
in_compare_to_string a string to be compared to in_string.
out_comparison on exit, a comparison result indicating whether in_string is greater than, less than or equal to in_compare_to_string.
+
+
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
+ +
+

+ +

+
+ + + + + + + + + +
void kim_string_free (kim_string_t *  io_string  ) 
+
+
+ +

+Free memory associated with a string. +

+

Parameters:
+ + +
io_string a string to be freed. Set to NULL on exit.
+
+ +
+

+

Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/group__kim__types__reference.html b/doc/kim/html/group__kim__types__reference.html new file mode 100644 index 0000000000..c46ec73e58 --- /dev/null +++ b/doc/kim/html/group__kim__types__reference.html @@ -0,0 +1,761 @@ + + +Kerberos Identity Management: KIM Types and Constants + + + + +

KIM Types and Constants

+

+

Defines

+ +

Typedefs

+ +

Enumerations

+ +

Functions

+ +

Define Documentation

+ +
+
+ + + + +
#define KIM_NO_ERROR   ((kim_error_t) NULL)
+
+
+ +

+The kim_error_t returned when no error occurred. Does not need to be freed with kim_error_free(). +

+

+ +

+
+ + + + +
#define KIM_NO_ERROR_ECODE   ((kim_error_code_t) 0)
+
+
+ +

+The kim_error_code_t for KIM_NO_ERROR. +

+

+ +

+
+ + + + +
#define KIM_IDENTITY_ANY   ((kim_identity_t) NULL)
+
+
+ +

+Constant to specify any Kerberos identity is acceptable. +

+

+ +

+
+ + + + +
#define KIM_OPTIONS_DEFAULT   ((kim_options_t) NULL)
+
+
+ +

+Specifies the user's default options. +

+

+ +

+
+ + + + +
#define KIM_OPTIONS_START_IMMEDIATELY   ((kim_time_t) 0)
+
+
+ +

+Specifies that credentials should be valid immediately. +

+

+ +

+
+ + + + + + + + + +
#define kim_comparison_is_less_than (c   )    (c < 0)
+
+
+ +

+Convenience macro for interpreting kim_comparison_t. +

+

+ +

+
+ + + + + + + + + +
#define kim_comparison_is_equal_to (c   )    (c == 0)
+
+
+ +

+Convenience macro for interpreting kim_comparison_t. +

+

+ +

+
+ + + + + + + + + +
#define kim_comparison_is_greater_than (c   )    (c > 0)
+
+
+ +

+Convenience macro for interpreting kim_comparison_t. +

+

+

Typedef Documentation

+ +
+
+ + + + +
typedef int kim_credential_state_t
+
+
+ +

+The state of a credential. See kim_credential_state_enum for possible values. +

+

+ +

+
+ + + + +
typedef uint32_t kim_prompt_type_t
+
+
+ +

+The type of prompt which needs to be displayed. This value determines what type of user interface is displayed. See Providing a Custom Prompt Callback for more information. +

+

+ +

+
+ + + + +
typedef kim_error_code_t(* kim_prompt_callback_t)(kim_options_t *io_options, kim_prompt_type_t in_type, kim_string_t in_title, kim_string_t in_message, kim_string_t in_description, void **out_reply)
+
+
+ +

+The prompt callback used to display a prompt to the user. See Providing a Custom Prompt Callback for more information. +

+

+ +

+
+ + + + +
typedef int32_t kim_error_code_t
+
+
+ +

+The KIM String type. See KIM String Overview for more information. +

+

+ +

+
+ + + + +
typedef int64_t kim_time_t
+
+
+ +

+A time value represented in seconds since January 1, 1970. +

+

+ +

+
+ + + + +
typedef int64_t kim_lifetime_t
+
+
+ +

+A duration represented in seconds. +

+

+ +

+
+ + + + +
typedef uint64_t kim_count_t
+
+
+ +

+An quantity, usually used to return the number of elements in an array. +

+

+ +

+
+ + + + +
typedef int kim_boolean_t
+
+
+ +

+A boolean value. 0 means false, all other values mean true. +

+

+ +

+
+ + + + +
typedef int kim_comparison_t
+
+
+ +

+A comparison between two sortable objects.

    +
  • Less than 0 means the first object is less than the second.
    • +
  • 0 means the two objects are identical.
    • +
  • Greater than 0 means the first object is greater than the second.
    Note:
    Convenience macros are provided for interpreting kim_comparison_ts to improve code readability. See kim_comparison_is_less_than(), kim_comparison_is_equal() and kim_comparison_is_greater_than()
    +
    • +
+ +
+

+ +

+
+ + + + +
typedef const char* kim_string_t
+
+
+ +

+The KIM String type. See KIM String Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_error_opaque* kim_error_t
+
+
+ +

+A KIM Error object. See KIM Error Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_identity_opaque* kim_identity_t
+
+
+ +

+A KIM Principal object. See KIM Identity Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_options_opaque* kim_options_t
+
+
+ +

+A KIM Options object. See KIM Options Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_selection_hints_opaque* kim_selection_hints_t
+
+
+ +

+A KIM Selection Hints object. See KIM Selection Hints Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_favorite_identities_opaque* kim_favorite_identities_t
+
+
+ +

+A KIM Favorite Realms object. See KIM Favorite Identities Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_preferences_opaque* kim_preferences_t
+
+
+ +

+A KIM Preferences object. See KIM Preferences Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_ccache_iterator_opaque* kim_ccache_iterator_t
+
+
+ +

+A KIM CCache Iterator object. See Acquiring a CCache from the Cache Collection for more information. +

+

+ +

+
+ + + + +
typedef struct kim_ccache_opaque* kim_ccache_t
+
+
+ +

+A KIM CCache object. See KIM CCache Overview for more information. +

+

+ +

+
+ + + + +
typedef struct kim_credential_iterator_opaque* kim_credential_iterator_t
+
+
+ +

+A KIM Credential Iterator object. See Iterating over the Credentials in a CCache for more information. +

+

+ +

+
+ + + + +
typedef struct kim_credential_opaque* kim_credential_t
+
+
+ +

+A KIM Credential object. See KIM Credential Overview for more information. +

+

+

Enumeration Type Documentation

+ +
+
+ + + + +
enum kim_credential_state_enum
+
+
+ +

+Possible credential states. Credentials may be:

    +
  • valid - The credential can be used.
    • +
  • expired - The credential's lifetime has been exceeded.
    • +
  • not_yet_valid - The credential is post dated and the time when it becomes valid has not yet been reached.
    • +
  • needs_validation - The credential is post-dated and although the time when it becomes valid has been reached it has not yet been validated.
    • +
  • address_mismatch - The credential contains IP address(es) which do not match the host's local address(es).
    • +
+ +
+

+

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_code_t kim_prompt_callback_default (kim_options_t *  io_options,
kim_prompt_type_t  in_type,
kim_string_t  in_title,
kim_string_t  in_message,
kim_string_t  in_description,
void **  out_reply 
)
+
+
+ +

+The default prompt callback. See Providing a Custom Prompt Callback for more information. +

+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_code_t kim_prompt_callback_gui (kim_options_t *  io_options,
kim_prompt_type_t  in_type,
kim_string_t  in_title,
kim_string_t  in_message,
kim_string_t  in_description,
void **  out_reply 
)
+
+
+ +

+The graphical prompt callback. See Providing a Custom Prompt Callback for more information. +

+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_code_t kim_prompt_callback_cli (kim_options_t *  io_options,
kim_prompt_type_t  in_type,
kim_string_t  in_title,
kim_string_t  in_message,
kim_string_t  in_description,
void **  out_reply 
)
+
+
+ +

+The command line prompt callback. See Providing a Custom Prompt Callback for more information. +

+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kim_error_code_t kim_prompt_callback_none (kim_options_t *  io_options,
kim_prompt_type_t  in_type,
kim_string_t  in_title,
kim_string_t  in_message,
kim_string_t  in_description,
void **  out_reply 
)
+
+
+ +

+The prompt callback which always returns an error. Use to turn off prompting entirely.

Note:
Using this callback may prevent the user from authenicating. See Providing a Custom Prompt Callback for more information.
+ +
+

+

Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/index.html b/doc/kim/html/index.html new file mode 100644 index 0000000000..fccd684de7 --- /dev/null +++ b/doc/kim/html/index.html @@ -0,0 +1,89 @@ + + +Kerberos Identity Management: Kerberos Identity Management (KIM) API Documentation + + + + +

Kerberos Identity Management (KIM) API Documentation

+

+

+Introduction

+The Kerberos Identity Management API is a high level API for managing the selection and management of Kerberos credentials. It is intended for use by applications, credential management applications (eg: kinit, kpasswd, etc) and internally by the Kerberos libraries. Under some circumstances client applications may also benefit from the Kerberos Identity Management API.

+API Conventions

+Although KIM currently only provides a C API, it attempts to make that API as object-oriented as possible. KIM functions are grouped by object and all of the object types are opaque, including errors. The reason for this is two-fold. First, the KIM API is rather large. Grouping functions by object allows the API to be broken up into smaller, more manageable chunks. Second, providing an object-like C API will make it easier to port to object oriented languages.

+Because C lacks classes and other object oriented syntax, KIM functions adhere to the following naming conventions to make functions easier to identify:

+

+ + + + +

+Terminology

+Kerberos organizes its authentication tokens by client identity (the name of the user) and service identity (the name of a service). The following terms are used throughout this documentation:

+

+ + + +

+Client Identity Selection APIs

+KIM provides high level APIs for applications to select which client identity to use. Use of these APIs is intended to replace the traditional "default ccache" mechanism previously used by Kerberos.

+KIM Selection Hints (kim_selection_hints_t) controls options for selecting a client identity:

+

+KIM Identity (kim_identity_t) provides an immutable Kerberos identity object

+

+Credential Management APIs

+KIM also provides APIs for acquiring new credentials over the network by contacting a KDC and for viewing and modifying the existing credentials in the cache collection

+Whether or not you use the credential or ccache APIs depends on whether you want KIM to store any newly acquired credentials in the cache collection. KIM ccache APIs always create a ccache in the cache collection containing newly acquired credentials whereas the KIM credential APIs just return a credential object. In general most callers want to store newly acquired credentials and should use the KIM ccache APIs when acquiring credentials.

+KIM CCache (kim_ccache_t) manipulates credential caches in the cache collection:

+

+KIM Credential (kim_credential_t) manipulates credentials:

+

+KIM Options (kim_options_t) control options for credential acquisition:

+

+KIM Realms List (kim_favorite_identities_t) views and edits the current user's favorite realms list:

+

+KIM Preferences (kim_preferences_t) views and edits the current user's preferences:

+

+Miscellaneous APIs

+The high and low level APIs depend on the following basic utility classes to manage generic types.

+KIM String (kim_string_t) provides memory management for an immutable string:

+

+KIM Error (kim_error_t) provides a machine and user-readable error message:

+

+Types and Constants

+ +
Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_ccache_overview.html b/doc/kim/html/kim_ccache_overview.html new file mode 100644 index 0000000000..dded05fcf7 --- /dev/null +++ b/doc/kim/html/kim_ccache_overview.html @@ -0,0 +1,66 @@ + + +Kerberos Identity Management: KIM CCache Overview + + + + +

KIM CCache Overview

+Introduction

+Kerberos credentials are stored in "ccaches" (short for "credentials caches"). The set of all ccaches which the KIM can use is called the "cache collection". Each ccache has a name and type which uniquely identify it in the cache collection and a client identity. The ccache's client identity is the identity whose credentials are stored in the ccache. This allows for easy lookup of all the credentials for a given identity.

+KIM attempts to preserve a one-to-one relationship between client identities and ccaches. If the KIM is used to manipulate the cache collection, there will be one ccache per identity. However, because low-level APIs allow callers to create multiple ccaches for the same client identity or a single ccache containing credentials for different client identities, KIM handles those situations. In general when searching KIM will find the first ccache matching the requested client identity. It will not find credentials for the requested client identity if they are in a ccache with a different client identity.

+The kim_ccache_t object is a reference to a ccache in the cache collection. If other applications make changes to the the ccache pointed to by a KIM ccache object, the object will immediately show those changes. KIM performs locking on the cache collection to prevent deadlocks and maintain a consistent behavior when multiple applications attempt to modify the cache collection.

+

Note:
KIM ccache APIs are intended for applications and system tools which manage credentials for the user. They are not a substitute for krb5 and GSSAPI functions which obtain service credentials for the purpose of authenticating a client to an application server.
+

+Acquiring a CCache from the Cache Collection

+KIM provides a simple iterator API for iterating over the ccaches in the cache collection. First, call kim_ccache_iterator_create() to obtain an iterator for the cache collection. Then loop calling kim_ccache_iterator_next() until either you find the ccache you are looking for or the API returns a NULL ccache, indicating that there are no more ccaches in the cache collection. When you are done with the iterator, call kim_ccache_iterator_free().

+

Note:
kim_ccache_iterator_next() returns ccache objects which must be freed with kim_ccache_free() to avoid leaking memory.
+KIM also provides a convenient API kim_ccache_create_from_client_identity() which returns the ccache for a specific client identity, if any exists. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity().

+Acquiring Credentials from the Default CCache

+kim_ccache_create_from_default() returns the default ccache. The default ccache is a legacy concept which was replaced by selection hints. Prior to the existence of selection hints, applications always looked at the default ccache for credentials. By setting the system default ccache, users could manually control which credentials each application used. As the number of ccaches and applications has grown, this mechanism has become unusable. You should avoid using this API whenever possible.

+Acquiring New Credentials in a CCache

+KIM provides the kim_ccache_create_new() API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

+kim_ccache_create_new_if_needed() searches the cache collection for a ccache for the client identity and if no appropriate ccache is available, attempts to acquire new credentials and store them in a new ccache. Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user. This function exists for convenience and to avoid code duplication. It can be trivially implemented using kim_ccache_create_from_client_identity() and kim_ccache_create_new().

+KIM provides the kim_ccache_create_from_keytab() to create credentials using a keytab and store them in the cache collection. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

+Validating Credentials in a CCache

+A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.

+KIM provides the kim_ccache_validate() API to validate the TGT credential in a ccache. Note that this API replaces any existing credentials with the validated credential.

+Renewing Credentials in a CCache

+A renewable credential can be used to obtain a new identical credential without resending secret information (such as a password) to the KDC. A credential may only be renewed during its renewal lifetime and while valid.

+KIM provides the kim_ccache_renew() API to renew the TGT credential in a ccache. Note that this API replaces any existing credentials with the renewed credential.

+Verifying Credentials in a CCache

+When a program acquires TGT credentials for the purpose of authenticating itself to the machine it is running on, it is insufficient for the machine to assume that the caller is authorized just because it got credentials. Instead, the credentials must be verified using a key the local machine. The reason this is necessary is because an attacker can trick the machine into obtaining credentials from any KDC, including malicious ones with the same realm name as the local machine's realm. This exploit is called the Zanarotti attack.

+In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_ccache_verify() API to verify credentials directly.

+The most common reason for using kim_ccache_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_ccache_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_ccache_verify().

+The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_ccache_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

+kim_ccache_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

+Examining CCache Properties

+ + + + + + + + +See KIM CCache Reference Documentation and KIM CCache Iterator Reference Documentation for information on specific APIs.
Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_credential_overview.html b/doc/kim/html/kim_credential_overview.html new file mode 100644 index 0000000000..cdf33a1011 --- /dev/null +++ b/doc/kim/html/kim_credential_overview.html @@ -0,0 +1,63 @@ + + +Kerberos Identity Management: KIM Credential Overview + + + + +

KIM Credential Overview

+Introduction

+A Kerberos credential (also called a "Kerberos ticket") is a time-limited token issued by a KDC which authenticates the entity named by the credential's client identity to the service named by the credential's service identity.

+The kim_credential_t object contains a single Kerberos credential. KIM credentials objects are always copies of credentials, not references to credentials stored in the cache collection. Modifying credential objects in the ccache collection will not change any existing KIM credential objects.

+KIM credential APIs are intended for applications and system tools which manage credentials for the user. They are not a substitute for krb5 and GSSAPI functions which obtain service credentials for the purpose of authenticating a client to an application server.

+

Note:
Many of the APIs listed below have equivalent functions which operate on ccaches. In most cases applications will want to use the ccache versions of these APIs since they automatically store any newly created credentials. See KIM CCache Overview for more information.
+

+Acquiring New Credentials

+KIM provides the kim_credential_create_new() API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

+KIM provides the kim_credential_create_from_keytab() to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

+Validating Credentials

+A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.

+KIM provides the kim_credential_validate() API to validate a credential. Note that this API replaces the credential object with a new validated credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the validated credential or use kim_ccache_validate() instead.

+Renewing Credentials

+A renewable credential can be used to obtain a new identical credential without resending secret information (such as a password) to the KDC. A credential may only be renewed during its renewal lifetime and while valid.

+KIM provides the kim_credential_renew() API to renew a credential. Note that this API replaces the credential object with a new renewed credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the renewed credential or use kim_ccache_renew() instead.

+Storing Credentials in the Cache Collection

+KIM credential objects may be stored in the ccache collection using kim_credential_store(). This function runs any KIM authentication plugins on the credential and if the plugins return successfully, creates a new ccache for the credential's client identity in the cache collection and stores the credential in that ccache. Any existing ccaches and credentials for that client identity will be overwritten. kim_credential_store() may optionally return a kim_ccache_t object for the new ccache if you need to perform further operations on the new ccache.

+Most of the time if you plan to store the credentials you are manipulating, you should use one of KIM ccache APIs. These functions perform the same operations except that they also call kim_credential_store() any time the credential object changes. See KIM CCache Overview for more information.

+Iterating over the Credentials in a CCache

+KIM provides a simple iterator API for iterating over the credentials in a ccache. First, call kim_credential_iterator_create() to obtain an iterator for a ccache. Then loop calling kim_credential_iterator_next() until either you find the credential you are looking for or the API returns a NULL credential, indicating that there are no more credentials in the ccache. When you are done with the iterator, call kim_credential_iterator_free().

+

Note:
kim_credential_iterator_next() returns credential objects which must be freed with kim_credential_free() to avoid leaking memory.
+

+Verifying Credentials

+When a program acquires TGT credentials for the purpose of authenticating itself to the machine it is running on, it is insufficient for the machine to assume that the caller is authorized just because it got credentials. Instead, the credentials must be verified using a key the local machine. The reason this is necessary is because an attacker can trick the machine into obtaining credentials from any KDC, including malicious ones with the same realm name as the local machine's realm. This exploit is called the Zanarotti attack.

+In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_credential_verify() API to verify credentials directly.

+The most common reason for using kim_credential_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_credential_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_credential_verify().

+The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_credential_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

+kim_credential_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

+Examining Credential Properties

+ + + + + + + +See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.
Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_error_overview.html b/doc/kim/html/kim_error_overview.html new file mode 100644 index 0000000000..7f3d821c04 --- /dev/null +++ b/doc/kim/html/kim_error_overview.html @@ -0,0 +1,16 @@ + + +Kerberos Identity Management: KIM Error Overview + + + + +

KIM Error Overview

An error object. Error objects consist of a machine readable error code for for programmatic error handling and a string describing the error. All KIM APIs return kim_errors with the exception of memory deallocation functions and the kim_error_t APIs which return pieces of a kim_error_t object.

+Functions which return successfully will return KIM_NO_ERROR (NULL). Because KIM_NO_ERROR does not need to be freed, you may use if-ladders or goto-style error handling when calling the KIM APIs. In addition, kim_error_free() may be called on KIM_NO_ERROR.

+

Note:
Certain kim_error_t objects are preallocated by the libraries avoid exacerbating existing problems while trying to report an error. For example, the out of memory error object is preallocated. It is safe to call kim_error_free() on these errors, although the function may not actually free the object.
+By providing an error object rather than a numeric code, the KIM APIs can tailor error strings to the circumstances of the error. So rather than returning error strings like "Client not found in Kerberos database", we can report "'user@REALM' not found in Kerberos database" while still providing the machine readable error KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN.

+See KIM Error Reference Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_favorite_identities_overview.html b/doc/kim/html/kim_favorite_identities_overview.html new file mode 100644 index 0000000000..ae5529d4dc --- /dev/null +++ b/doc/kim/html/kim_favorite_identities_overview.html @@ -0,0 +1,24 @@ + + +Kerberos Identity Management: KIM Favorite Identities Overview + + + + +

KIM Favorite Identities Overview

+Introduction

+As Kerberos becomes more widespread, the number of possible Kerberos identities and realms a user might want to use will become very large. Sites may list hundreds of realms in their Kerberos configuration files. In addition, sites may wish to use DNS SRV records to avoid having to list all the realms they use in their Kerberos configuration. As a result, the list of realms in the Kerberos configuration may be exceedingly large and/or incomplete. Users may also use multiple identities from the same realm.

+On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of identities for the user to select from. Depending on what is appropriate for the platform, identities may be displayed in a popup menu or other list.

+To solve this problem, the KIM maintains a list of favorite identities specifically for identity selection. This list is a set of unique identities in alphabetical order (as appropriate for the user's language localization).

+On most platforms the list of favorite identities has both an administrator preference and a user preference which overrides it. The administrator preference exists only to initialize the favorite identities for new user accounts. Once the user modifies the list their favorite identities may diverge from the site favorite identities preference.

+

Note:
The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.
+Most callers will not need to use the favorite identities APIs. However if you are implementing your own graphical prompt callback or a credential management application, you may to view and/or edit the user's favorite identities.

+Viewing and Editing the Favorite Identities

+First, you need to acquire the Favorite Identities stored in the user's preferences using kim_preferences_create() and kim_preferences_get_favorite_identities(). Or you can use kim_favorite_identities_create() to get an empty identities list if you want to overwrite the user's identities list entirely. See KIM Preferences Overview for more information on modifying the user's preferences.

+Then use kim_favorite_identities_get_number_of_identities() and kim_favorite_identities_get_identity_at_index() to display the identities list. Use kim_favorite_identities_add_identity() and kim_favorite_identities_remove_identity() to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list.

+Once you are done editing the identities list, store changes in the user's preference file using kim_preferences_set_favorite_identities() and kim_preferences_synchronize().

+See KIM Favorite Identities Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_identity_overview.html b/doc/kim/html/kim_identity_overview.html new file mode 100644 index 0000000000..6a3aa1678b --- /dev/null +++ b/doc/kim/html/kim_identity_overview.html @@ -0,0 +1,46 @@ + + +Kerberos Identity Management: KIM Identity Overview + + + + +

KIM Identity Overview

+Introduction

+Identities in Kerberos are named by "principals". These identies may be people (users) or services (a server running on a host). When Kerberos issues credentials which authenticate one identity to another, the identity being authenticated is called the "client identity" and the identity being authenticated to is called the "service identity".

+Kerberos identities are made up of one or more components, as well as the Kerberos realm the entity belongs to. For client identities the first component is usually the client username (eg: "jdoe"). For service identities the first component is the name of the service (eg: "imap").

+Kerberos identities have both a binary (opaque) representation and also a string representation. The string representation consists of the components separated by '/' followed by an '@' and then the realm. For example, the identity "jdoe/admin@EXAMPLE.COM" represents John Doe's administrator identity at the realm EXAMPLE.COM. Note that identity components may contain both '/' and '@' characters. When building a identity from its string representation these syntactic characters must be escaped with '\'.

+Creating and Displaying Identities

+KIM Identities can be generated from components, their escaped string representation or from a krb5_principal. Once you have a KIM identity object, you can also get the component, string or krb5_principal representations back out:

+

+ + + +
Note:
If you need to know if two identity objects refer to the same entity, use kim_identity_compare().
+

+Choosing a Client Identity

+Unfortunately most of the time applications don't know what client identity to use. Users may have identities for multiple Kerberos realms, as well as multiple identities in a single realm (such as a user and administrator identity).

+To solve this problem, kim_selection_hints_get_identity() takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See KIM Selection Hints Overview for more information.

+Changing a Identity's Password

+Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.

+kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.

+

Note:
Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).
+See KIM Identity Reference Documentation for information on specific APIs.
Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_options_overview.html b/doc/kim/html/kim_options_overview.html new file mode 100644 index 0000000000..bd7ad8466d --- /dev/null +++ b/doc/kim/html/kim_options_overview.html @@ -0,0 +1,49 @@ + + +Kerberos Identity Management: KIM Options Overview + + + + +

KIM Options Overview

+Introduction

+Kerberos Identity Management Options (kim_options_t) allows you to control how the Kerberos library obtains credentials. When the options structure is initialized with kim_options_create(), each option is filled in with a default value which can then be modified with the kim_options_set_*() APIs. If you only want to use the default values, you may pass KIM_OPTIONS_DEFAULT into any KIM function that takes a kim_options_t.

+KIM options fall into two major categories: options for controlling how credentials are acquired and options for controlling what properties the newly acquired credentials will have:

+Options for Controlling Credential Acquisition

+In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. These secrets may be a certificate, password, SecurID pin, or information from a smart card. If obtaining the secret requires interaction with the user, the Kerberos libraries call a "prompter callback" to display a dialog or command line prompt to request information from the user. If you want to provide your own custom dialogs or command line prompts, the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.

+Providing a Custom Prompt Callback

+All secrets are obtained from the user through a kim_prompt_callback_t. By default, options use kim_prompt_callback_default, which presents an expanding dialog to request information from the user, or if no graphical access is available, a command line prompt.

+KIM also provides three other callbacks: kim_prompt_callback_gui only presents a dialog and returns an error if there is no graphical access. kim_prompt_callback_cli only presents a command line interface and returns an error if there is no controlling terminal available. kim_prompt_callback_none always returns an error.

+Using kim_options_set_prompt_callback(), you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with kim_options_set_data() for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.

+Prefetching Prompt Responses

+Sometimes you may have already collected some of the information needed to acquire Kerberos credentials. Rather than creating a prompt callback, you may also prefetch responses to the options directly with kim_options_set_prompt_response(). Once you have associated your response with a given prompt type, the Kerberos libraries will use this response for the first prompt of that type rather than calling the prompt callback to obtain it.

+Note that even if you prefetch responses, the prompt callback may still be called if you did not provide all the information required for the identity. You may specify the kim_prompt_callback_none prompt callback to prevent prompting from occuring entirely, however, doing so will tie your application to a particular Kerberos configuration. For example, if your application assumes that all identities only require a password, it will not be able to acquire credentials at sites using SecurID pins.

+Options for Controlling Credential Properties

+Kerberos credentials have a number of different properties which can be requested when credentials are acquired. These properties control when and for how long the credentials are valid and what you can do with them.

+Note that setting these properties in the KIM options only changes what the Kerberos libraries request from the KDC. The KDC itself may choose not to honor your requested properties if they violate the site security policy. For example, most sites place an upper bound on how long credentials may be valid. If you request a credential lifetime longer than this upper bound, the KDC may return credentials with a shorter lifetime than you requested.

+Credential Lifetime

+Kerberos credentials have start time and a lifetime during which they are valid. Once the lifetime has passed, credentials "expire" and can no longer be used.

+The requested credential start time can be set with kim_options_set_start_time() and examined with kim_options_get_start_time(). The requested credential lifetime can be set with kim_options_set_lifetime() and examined with kim_options_get_lifetime().

+Renewable Credentials

+Credentials with very long lifetimes are more convenient since the user does not have authenticate as often. Unfortunately they are also a higher security risk: if credentials are stolen they can be used until they expire. Credential renewal exists to compromise between these two conflicting goals.

+Renewable credentials are TGT credentials which can be used to obtain new TGT credentials without reauthenticating. By regularly renewing credentials the KDC has an opportunity to check to see if the client's credentials have been reported stolen and refuse to renew them. Renewable credentials have a "renewal lifetime" during which credentials can be renewed. This lifetime is relative to the original credential start time. If credentials are renewed shortly before the end of the renewal lifetime, their lifetime will be capped to the end of the renewal lifetime.

+Note that credentials must be valid to be renewed and therefore may not be an appropriate solution for all use cases. Sites which use renewable credentials often create helper processes running as the user which will automatically renew the user's credentials when they get close to expiration.

+Use kim_options_set_renewable() to change whether or not the Kerberos libraries request renewable credentials and kim_options_get_renewable() to find out the current setting. Use kim_options_set_renewal_lifetime() to change the requested renewal lifetime and kim_options_get_renewal_lifetime() to find out the current value.

+Addressless Credentials

+Traditionally Kerberos used the host's IP address as a mechanism to restrict the user's credentials to a specific host, thus making it harder to use stolen credentials. When authenticating to a remote service with credentials containing addresses, the remote service verifies that the client's IP address is one of the addresses listed in the credential. Unfortunately, modern network technologies such as NAT rewrite the IP address in transit, making it difficult to use credentials with addresses in them. As a result, most Kerberos sites now obtain addressless credentials.

+Use kim_options_set_addressless() to change whether or not the Kerberos libraries request addressless credentials. Use kim_options_get_addressless() to find out the current setting.

+Forwardable Credentials

+Forwardable credentials are TGT credentials which can be forwarded to a service you have authenticated to. If the credentials contain IP addresses, the addresses are changed to reflect the service's IP address. Credential forwarding is most commonly used for Kerberos-authenticated remote login services. By forwarding TGT credentials through the remote login service, the user's credentials will appear on the remote host when the user logs in.

+The forwardable flag only applies to TGT credentials.

+Use kim_options_set_forwardable() to change whether or not the Kerberos libraries request forwardable credentials. Use kim_options_get_forwardable() to find out the current setting.

+Proxiable Credentials

+Proxiable credentials are similar to forwardable credentials except that instead of forwarding the a TGT credential itself, a service credential is forwarded instead. Using proxiable credentials, a user can permit a service to perform a specific task as the user using one of the user's service credentials.

+Like forwardability, the proxiable flag only applies to TGT credentials. Unlike forwarded credentials, the IP address of proxiable credentials are not modified for the service when being proxied. This can be solved by also requesting addressless credentials.

+Use kim_options_set_proxiable() to change whether or not the Kerberos libraries request proxiable credentials. Use kim_options_get_proxiable() to find out the current setting.

+Service Name

+Normally users acquire TGT credentials (ie "ticket granting tickets") and then use those credentials to acquire service credentials. This allows Kerberos to provide single sign-on while still providing mutual authentication to services. However, sometimes you just want an initial credential for a service. KIM options allows you to set the service name with kim_options_set_service_name() and query it with kim_options_get_service_name().

+See KIM Options Reference Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_preferences_overview.html b/doc/kim/html/kim_preferences_overview.html new file mode 100644 index 0000000000..b388729bb7 --- /dev/null +++ b/doc/kim/html/kim_preferences_overview.html @@ -0,0 +1,28 @@ + + +Kerberos Identity Management: KIM Preferences Overview + + + + +

KIM Preferences Overview

+Introduction

+In addition to the site preferences stored in the Kerberos configuration, users may also want to have their own personal preferences for controlling credential acquisition. As a result, KIM provides user preferences for initial credential options and user interface behavior such as the default client identity and the favorite identities list.

+Viewing and Editing the Preferences

+In order to view and edit the user's preferences, call kim_preferences_create() to acquire a preferences object containing the user's preferences. You can examine preferences with the functions starting with "kim_preferences_get_" and change preferences with the functions starting with "kim_preferences_set_". Once you are done making changes, you can write changes back out to the user's preferences with kim_preferences_synchronize().

+

Note:
The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.
+

+Initial Credential Options Preferences

+KIM provides user preferences for initial credential options. These are the options kim_options_create() will use when creating a new KIM options object. They are also the options specified by KIM_OPTIONS_DEFAULT. You can view and edit the initial credential options using kim_preferences_get_options() and kim_preferences_set_options().

+

Note:
Not all credential options in the kim_options_t object have corresponding user preferences. For example, the prompt callback function is not stored in the user preferences since it has no meaning outside of the current application. Some options which are not currently stored in the preferences may be stored there in the future.
+If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the initial credential options preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_options() is set to TRUE, you should store the options used to get credentials with kim_preferences_set_options().

+Client Identity Preferences

+KIM also provides user preferences for the default client identity. This identity is used whenever KIM needs to display a graphical dialog for credential acquisition but does not know what client identity to use. You can view and edit the default client identity using kim_preferences_get_client_identity() and kim_preferences_set_client_identity().

+If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the client identity preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_client_identity() is set to TRUE, you should store the client identity for which credentials were acquired using kim_preferences_set_client_identity().

+Favorite Identities Preferences

+When presenting a graphical interface for credential acquisition, KIM may need to display a list of identities for the user to select from. This list is generated by the user's favorite identities preference. You can view and edit the favorite identities preference using kim_preferences_get_favorite_identities() and kim_preferences_set_favorite_identities(). Please see the KIM Favorite Identities Overview for more information.

+See KIM Preferences Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_selection_hints_overview.html b/doc/kim/html/kim_selection_hints_overview.html new file mode 100644 index 0000000000..d9be9d2603 --- /dev/null +++ b/doc/kim/html/kim_selection_hints_overview.html @@ -0,0 +1,55 @@ + + +Kerberos Identity Management: KIM Selection Hints Overview + + + + +

KIM Selection Hints Overview

+Introduction

+Most users belong to multiple organizations and thus need to authenticate to multiple Kerberos realms. Traditionally Kerberos sites solved this problem by setting up a cross-realm relationship, which allowed the user to use TGT credentials for their client identity in one realm to obtain credentials in another realm via cross-realm authentication. As a result users could acquire credentials for a single client identity and use them everywhere.

+Setting up cross-realm requires that realms share a secret, so sites must coordinate with one another to set up a cross-realm relationship. In addition, sites must set up authorization policies for users from other realms. As Kerberos becomes increasingly wide-spread, many realms will not have cross-realm relationships, and users will need to manually obtain credentials for their client identity at each realm (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc). As a result, users will often have multiple credentials caches, one for each client identity.

+Unfortunately this presents a problem for applications which need to obtain service credentials. Which client identity should they use? Rather than having each application to manually search the cache collection, KIM provides a selection hints API for choosing the best client identity. This API is intended to simplify the process of choosing credentials and provide consistent behavior across all applications.

+Searching the cache collection for credentials may be expensive if there are a large number of caches. If credentials for the client identity are expired or not present, KIM may also wish to prompt the user for new credentials for the appropriate client identity. As a result, applications might want to remember which client identity worked in the past and always request credentials using that identity.

+Creating KIM Selection Hints

+A KIM selection hints object consists of an application identifier and one or more pieces of information about the service the client application will be contacting. The application identifier is used by user preferences to control how applications share cache entries. It is important to be consistent about what application identifier you provide. Java-style identifiers are recommended to avoid collisions.

+Selection Hint Search Behavior

+When using selection hints to search for an appropriate client identity, KIM uses a consistent hint search order. This allows applications to specify potentially contradictory information without preventing KIM from locating a single ccache. In addition the selection hint search order may change, especially if more hints are added.

+As a result, callers are encouraged to provide all relevant search hints, even if only a subset of those search hints are necessary to get reasonable behavior in the current implementation. Doing so will provide the most user-friendly selection experience.

+Currently the search order looks like this:

+

+For example, if you specify a service identity and a credential for that identity already exists in the ccache collection, KIM may use that ccache, even if your user and client realm entries in the selection hints would lead it to choose a different ccache. If no credentials for the service identity exist then KIM will fall back on the user and realm hints.

+

Note:
Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.
+

+Selecting an Identity Using Selection Hints

+Once you have provided search criteria for selecting an identity, use kim_selection_hints_get_identity() to obtain an identity object. You can then use kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.

+

Note:
kim_selection_hints_get_identity() obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call kim_selection_hints_get_identity() again.
+

+Selection Hint Caching Behavior

+In addition to using selection hints to search for an appropriate client identity, KIM can also use them to remember which client identity worked. KIM maintains a per-user cache mapping selection hints to identities so that applications do not have to maintain their own caches or present user interface for selecting which cache to use.

+When kim_selection_hints_get_identity() is called KIM looks up in the cache and returns the identity which the selection hints map to. If there is not a preexisting cache entry for the selection hints then kim_selection_hints_get_identity() will search for an identity and prompt the user if it cannot find an appropriate one.

+If the client identity returned by KIM authenticates and passes authorization checks, you should tell KIM to cache the identity by calling kim_selection_hints_remember_identity(). This will create a cache entry for the mapping between your selection hints and the identity so that subsequent calls to kim_selection_hints_get_identity() do not need to prompt the user.

+If the client identity returned by KIM fails to authenticate or fails authorization checks, you must call kim_selection_hints_forget_identity() to remove any mapping that already exists. After this function is called, future calls to kim_selection_hints_get_identity() will search for an identity again. You may also wish to call this function if the user changes your application preferences such that the identity might be invalidated.

+

Note:
It is very important that you call kim_selection_hints_forget_identity() if your application fails to successfully establish a connection with the server. Otherwise the user can get "stuck" using the same non-working identity if they chose the wrong one accidentally or if their identity information changes. Because only your application understands the authorization checksof the protocol it uses, KIM cannot tell whether or not the identity worked.
+If you wish to search and prompt for an identity without using the cached mappings, you can turn off the cached mapping lookups using kim_selection_hints_set_remember_identity(). This is not recommended for most applications since it will result in a lot of unnecessary searching and prompting for identities.

+

Note:
Because cache entries key off of selection hints, it is important to always specify the same hints when contacting a particular service. Otherwise KIM will not always find the cache entries.
+

+Selection Hint Prompting Behavior

+If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when kim_selection_hints_get_identity() is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.

+

Note:
Because of the caching behavior described above the user will only be prompted to choose an identity when setting up the application or when their identity stops working.
+In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with kim_selection_hints_set_application_name(). You can check what name will be used with kim_selection_hints_get_application_name().

+In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with kim_selection_hints_get_explanation(). You can find out what string will be used with kim_selection_hints_set_explanation().

+Since the user may choose to acquire credentials when selection an identity, KIM also provides kim_selection_hints_set_options() to set what credential acquisition options are used. kim_selection_hints_get_options() returns the options which will be used.

+If you need to disable user interaction, use kim_selection_hints_set_allow_user_interaction(). Use kim_selection_hints_get_allow_user_interaction() to find out whether or not user interaction is enabled. User interaction is enabled by default.

+See KIM Selection Hints Reference Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/kim_string_overview.html b/doc/kim/html/kim_string_overview.html new file mode 100644 index 0000000000..202d2e6798 --- /dev/null +++ b/doc/kim/html/kim_string_overview.html @@ -0,0 +1,14 @@ + + +Kerberos Identity Management: KIM String Overview + + + + +

KIM String Overview

A UTF8 string.

+Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.

+See KIM String Reference Documentation for information on specific APIs.

Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/modules.html b/doc/kim/html/modules.html new file mode 100644 index 0000000000..ee3e888cb5 --- /dev/null +++ b/doc/kim/html/modules.html @@ -0,0 +1,26 @@ + + +Kerberos Identity Management: Module Index + + + + +

Kerberos Identity Management Modules

Here is a list of all modules: +
Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  + +doxygen 1.5.3
+ + diff --git a/doc/kim/html/tab_b.gif b/doc/kim/html/tab_b.gif new file mode 100644 index 0000000000..0d623483ff Binary files /dev/null and b/doc/kim/html/tab_b.gif differ diff --git a/doc/kim/html/tab_l.gif b/doc/kim/html/tab_l.gif new file mode 100644 index 0000000000..9b1e6337c9 Binary files /dev/null and b/doc/kim/html/tab_l.gif differ diff --git a/doc/kim/html/tab_r.gif b/doc/kim/html/tab_r.gif new file mode 100644 index 0000000000..ce9dd9f533 Binary files /dev/null and b/doc/kim/html/tab_r.gif differ diff --git a/doc/kim/html/tabs.css b/doc/kim/html/tabs.css new file mode 100644 index 0000000000..c37faafe80 --- /dev/null +++ b/doc/kim/html/tabs.css @@ -0,0 +1,102 @@ +/* tabs styles, based on http://www.alistapart.com/articles/slidingdoors */ + +DIV.tabs +{ + float : left; + width : 100%; + background : url("tab_b.gif") repeat-x bottom; + margin-bottom : 4px; +} + +DIV.tabs UL +{ + margin : 0px; + padding-left : 10px; + list-style : none; +} + +DIV.tabs LI, DIV.tabs FORM +{ + display : inline; + margin : 0px; + padding : 0px; +} + +DIV.tabs FORM +{ + float : right; +} + +DIV.tabs A +{ + float : left; + background : url("tab_r.gif") no-repeat right top; + border-bottom : 1px solid #84B0C7; + font-size : x-small; + font-weight : bold; + text-decoration : none; +} + +DIV.tabs A:hover +{ + background-position: 100% -150px; +} + +DIV.tabs A:link, DIV.tabs A:visited, +DIV.tabs A:active, DIV.tabs A:hover +{ + color: #1A419D; +} + +DIV.tabs SPAN +{ + float : left; + display : block; + background : url("tab_l.gif") no-repeat left top; + padding : 5px 9px; + white-space : nowrap; +} + +DIV.tabs INPUT +{ + float : right; + display : inline; + font-size : 1em; +} + +DIV.tabs TD +{ + font-size : x-small; + font-weight : bold; + text-decoration : none; +} + + + +/* Commented Backslash Hack hides rule from IE5-Mac \*/ +DIV.tabs SPAN {float : none;} +/* End IE5-Mac hack */ + +DIV.tabs A:hover SPAN +{ + background-position: 0% -150px; +} + +DIV.tabs LI.current A +{ + background-position: 100% -150px; + border-width : 0px; +} + +DIV.tabs LI.current SPAN +{ + background-position: 0% -150px; + padding-bottom : 6px; +} + +DIV.nav +{ + background : none; + border : none; + border-bottom : 1px solid #84B0C7; +}