1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
/*
* Copyright 2005-2006 Massachusetts Institute of Technology.
* All Rights Reserved.
*
* Export of this software from the United States of America may
* require a specific license from the United States Government.
* It is the responsibility of any person or organization contemplating
* export to obtain such a license before exporting.
*
* WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
* distribute this software and its documentation for any purpose and
* without fee is hereby granted, provided that the above copyright
* notice appear in all copies and that both that copyright notice and
* this permission notice appear in supporting documentation, and that
* the name of M.I.T. not be used in advertising or publicity pertaining
* to distribution of the software without specific, written prior
* permission. Furthermore if you modify this software you must label
* your software as modified software and not distribute it in such a
* fashion that it might be confused with the original M.I.T. software.
* M.I.T. makes no representations about the suitability of
* this software for any purpose. It is provided "as is" without express
* or implied warranty.
*/
#ifndef KIM_H
#define KIM_H
#ifdef __cplusplus
extern "C" {
#endif
#include <kim/kim_types.h>
#include <kim/kim_errors.h>
#include <kim/kim_string.h>
#include <kim/kim_identity.h>
#include <kim/kim_options.h>
#include <kim/kim_selection_hints.h>
#include <kim/kim_preferences.h>
#include <kim/kim_credential.h>
#include <kim/kim_ccache.h>
/*!
* \mainpage Kerberos Identity Management (KIM) API Documentation
*
* \section introduction 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.
*
*
* \section conventions 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:
*
* \li Functions beginning with \b kim_object_create are constructors for an object of
* type kim_object. On success these functions return a newly allocated object which
* must later be freed by the caller.
*
* \li Functions of the form \b kim_object_copy are copy constructors. They instantiate
* a new object of kim_object from an object of the same type.
*
* \li Functions of the form \b kim_object_free are destructors for objects of type
* kim_object.
*
* \li Functions beginning with \b kim_object_get and \b kim_object_set
* examine and modify properties of objects of type kim_object.
*
* \li All KIM APIs except destructors and error management APIs return a
* KIM Error object (kim_error_t).
*
*
* \section terminology 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:
*
* \li <b>credential</b> - A token which authenticates a client identity to a
* service identity.
*
* \li <b>ccache</b> - Short for "credentials cache". A set of credentials for a single
* client identity.
*
* \li <b>cache collection</b> - The set of all credential caches.
*
* \li <b>default ccache</b> - A credentials cache that the Kerberos libraries will use
* if no ccache is specified by the caller. Use of the default
* ccache is now discouraged. Instead applications should use
* selection hints to choose an appropriate client identity.
*
* \section selection_api 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.
*
* <B>KIM Selection Hints (kim_selection_hints_t)</B> controls options for selecting
* a client identity:
* - \subpage kim_selection_hints_overview
* - \subpage kim_selection_hints_reference
*
* <B>KIM Identity (kim_identity_t)</B> provides an immutable Kerberos identity object
* - \subpage kim_identity_overview
* - \subpage kim_identity_reference
*
*
* \section management_api 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.
*
* <B>KIM CCache (kim_ccache_t)</B> manipulates credential caches in the cache collection:
* - \subpage kim_ccache_overview
* - \subpage kim_ccache_reference
*
* <B>KIM Credential (kim_credential_t)</B> manipulates credentials:
* - \subpage kim_credential_overview
* - \subpage kim_credential_reference
*
* <B>KIM Options (kim_options_t)</B> control options for credential acquisition:
* - \subpage kim_options_overview
* - \subpage kim_options_reference
*
* <B>KIM Preferences (kim_preferences_t)</B> views and edits the current user's preferences:
* - \subpage kim_preferences_overview
* - \subpage kim_preferences_reference
*
*
* \section utility_apis Miscellaneous APIs
*
* The high and low level APIs depend on the following basic utility classes
* to manage generic types.
*
* <B>KIM String (kim_string_t)</B> provides memory management for an immutable string:
* - \subpage kim_string_overview
* - \subpage kim_string_reference
*
*
*
* \section types Types and Constants
*
* \li \subpage kim_types_reference
*/
#ifdef __cplusplus
}
#endif
#endif /* KIM_H */
|
