diff options
Diffstat (limited to 'doc/ccapi/ccache-api-v2.html')
| -rwxr-xr-x | doc/ccapi/ccache-api-v2.html | 1217 |
1 files changed, 0 insertions, 1217 deletions
diff --git a/doc/ccapi/ccache-api-v2.html b/doc/ccapi/ccache-api-v2.html deleted file mode 100755 index b8d3f06e5772..000000000000 --- a/doc/ccapi/ccache-api-v2.html +++ /dev/null @@ -1,1217 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" - "http://www.w3.org/TR/REC-html40/loose.dtd"> -<HTML> -<HEAD> - <TITLE>Credentials Cache API v2 Specification</TITLE> -</HEAD> -<BODY> -<H1>Credentials Cache API v2 Specification</H1> -<H3>This version of the API is deprecated. <BR> -Please refer to CCAPI version 3 or later for the current API.</H3> - -<UL> - <LI><A HREF="#TypeDefinitions">Type Definitions</A> - - <UL CLASS=small> - <LI><A HREF="#cc_int32">cc_int32 & cc_uint32</A> - - <LI><A HREF="#cc_time_t">cc_time_t</A> - - <LI><A HREF="#cc_nc_flags">cc_nc_flags</A> - - <LI><A HREF="#typedefCC_Cred">cc_cred</A> - - <LI><A HREF="#typedefCC_Data">cc_data</A> - - <LI><A HREF="#typedefV4Cred_type">V4Cred_type</A> - - <LI><A HREF="#enumStringToKey_Type">StringToKey_Type</A> - - <LI><A HREF="#enumCc_cred_vers">cc_cred_vers</A> - - <LI><A HREF="#unionCred_ptr_union">cred_ptr_union</A> - - <LI><A HREF="#unionCred_union">cred_union</A> - - <LI><A HREF="#typdefInfoNC">infoNC</A> - - <LI><A HREF="#opaque_types">opaque types</A> - </UL> - - <LI><A HREF="#ErrorCodeDefinitions">Error Code Definitions</A> - - <LI><A HREF="#ImplementationNotes">Implementation Notes</A> - - <LI><A HREF="#FunctionDefinitions">Function Definitions</A> - - <UL> - <LI><A HREF="#MainCacheFunctions">Main Cache Functions</A> - - <UL CLASS=small> - <LI><A HREF="#cc_initialize">cc_initialize</A> - - <LI><A HREF="#cc_create">cc_create</A> - - <LI><A HREF="#cc_open">cc_open</A> - - <LI><A HREF="#cc_close">cc_close</A> - - <LI><A HREF="#cc_destroy">cc_destroy</A> - - <LI><A HREF="#cc_shutdown">cc_shutdown</A> - - <LI><A HREF="#cc_initialize">cc_initialize</A> - - <LI><A HREF="#cc_get_change_time">cc_get_change_time</A> - - <LI><A HREF="#cc_get_NC_info">cc_get_NC_info</A> - - <LI><A HREF="#cc_seq_fetch_NCs_begin">cc_seq_fetch_NCs_begin</A> - - <LI><A HREF="#cc_seq_fetch_NCs_next">cc_seq_fetch_NCs_next</A> - - <LI><A HREF="#cc_seq_fetch_NCs_end">cc_seq_fetch_NCs_end</A> - - </UL> - - <LI><A HREF="#NCFunctions">NC Functions</A> - - <UL CLASS=small> - <LI><A HREF="#cc_get_name">cc_get_name</A> - - <LI><A HREF="#cc_get_cred_version">cc_get_cred_version</A> - - <LI><A HREF="#cc_get_principal">cc_get_principal</A> - - <LI><A HREF="#cc_get_instance">cc_get_instance</A> - - <LI><A HREF="#cc_remove_cred">cc_remove_cred</A> - - <LI><A HREF="#cc_store">cc_store</A> - - <LI><A HREF="#cc_get_instance">cc_get_instance</A> - - <LI><A HREF="#cc_seq_fetch_creds_begin">cc_seq_fetch_creds_begin</A> - - <LI><A HREF="#cc_seq_fetch_creds_next">cc_seq_fetch_creds_next</A> - - <LI><A HREF="#cc_seq_fetch_creds_end">cc_seq_fetch_creds_end</A> - - <LI><A HREF="#cc_lock_request">cc_lock_request</A> - </UL> - - <LI><A HREF="#LiberationFunctions">Liberation Functions</A> - - <UL CLASS=small> - <LI><A HREF="#cc_free_principal">cc_free_principal</A> - - <LI><A HREF="#cc_free_name">cc_free_name</A> - - <LI><A HREF="#cc_free_creds">cc_free_creds</A> - - <LI><A HREF="#cc_free_NC_info">cc_free_NC_info</A> - </UL> - </UL> - - <LI><A HREF="#RevisionNotes">Revision History/Notes</A> - - <UL> - <LI><A HREF="#ChangesRev3">Changes made during revsion 3</A> - </UL> - - <LI><A HREF="#FutureIdeas">Ideas for Future Versions</A> - - <LI><A HREF="#Abstract">Abstract</A> -</UL> - -<P> -<HR> -<A NAME="Abstract"></A> - -<H2>Abstract</H2> - -<P>This is the specification for an API which provides Credentials -Cache services for both -<A HREF="http://web.mit.edu/kerberos/www/">Kerberos V5</A> and V4. -The idea behind this API is that multiple Kerberos implementations -can share a single Credentials Cache, mediated by this API -specification. On the Microsoft Windows platform this will allow -single-signon, even when more than one Kerberos DLL is in use on a -particular system. Ideally, this problem could be solved by -standardizing the Kerberos V5 API library interface. However, the -Kerberos API is complicated enough that this would be hard to -accomplish. Standardizing the interface for credentials cache access -is much simpler. This API has also been adopted in the MIT Kerberos -for the Macintosh implementation. - -<P>This specification has been revised to allow storage and -manipulation of both V4 and V5 tickets. A cache contains one or more -"Named Cache"s. It is assumed that V4 and V5 credentials would each -be stored in separate "Named Cache"s and not mixed in a single "Named -Cache". - -<P>Below, "NC" refers to "Named Cache".<BR> - - - -<P> -<HR> -<A NAME="RevisionNotes"></A> - -<H2><B>Revision History/Notes</B></H2> - -<H4>Original version (Draft Version 1)</H4> - -<P>1/27/96 by -<A HREF="http://web.mit.edu/tytso/www/home.html">Theodore Ts'o</A> - -<H4>Revision 2 (Draft Version 1)</H4> - -<P>970628 by <A HREF="http://www.umich.edu/~sgr">Steve Rothwell</A> -for the V4Cache Team (Paul Hill, Jenny Khuon, Jean Luker, Dave -Detlefs, Allan Bjorklund, & Steve Rothwell) - -<P><A NAME="ChangesRev3"></A> - -<H4>Revision 3 (Draft Version 1)</H4> - -<P>970725 by Steve Rothwell after initial implementation and alpha -release. The term "credentials cache" was previously used to mean -both "the main cache" and individual "named cache"s within the main -cache. I have started using the term "NC" for "named cache" to make -the distinction clearer and to reduce the overloading of the word -"cache". - -<H5>Changes made for revision 3 of this API:</H5> - -<UL> - <LI>Added cred version type to cc_create() & cc_open() - - <LI>New functions - - <UL> - <LI>cc_get_NC_info(), returns NC_info list for all NCs - - <LI>cc_free_NC_info(), frees NC_info list - - <LI>cc_get_cred_version(), returns version type of NC - - <LI>cc_get_name(), returns name of NC - - <LI>cc_free_name(), frees name aquired via cc_get_name() - - <LI>cc_seq_fetch_NCs(), iterate over all NCs - </UL> - - <LI>New return codes - - <UL> - <LI>CC_BAD_PARM - - <LI>CC_ERR_CACHE_ATTACH - - <LI>CC_ERR_CACHE_RELEASE - - <LI>CC_ERR_CACHE_FULL - - <LI>CC_ERR_CRED_VERSION - </UL> - - <LI>Modified functions - - <UL> - <LI>cc_create(), cc_open(), pass version type of NC - - <LI>cc_store(), cc_remove(), cc_ - </UL> - - <LI>New & Modified typedefs & data structures - - <UL> - <LI>cc_cred_vers { CC_CRED_VUNKNOWN, CC_CRED_V4, CC_CRED_V5 } - - <LI>cred_ptr_union : contains pointer to credentials (either V4 - or V5) - - <LI>cred_union : contains version type and cred_ptr_union - - <LI>modified V4Cred_type - - <LI>enum StringToKey_Type { STK_AFS or STK_DES } - - <LI>copies of the maximum V4 string size indicators - KRB_PRINCIPAL_SZ, KRB_SERVICE_SZ, KRB_INSTANCE_SZ, - KRB_REALM_SZ, ADDR_SZ - </UL> -</UL> - -<H4>Revision 4 (Draft Version 1)</H4> - -<P>970908 by Steve Rothwell to incorporate changes initiated by Ted -Tso. Further changes are expected in the comments for cc_create() and -cc_get_change_time(). - -<H4>Revision 4a (Final Version 1)</H4> - -<P>980603 by <A HREF="mailto:smcguire@mit.edu">Scott McGuire</A> to -correct typographical errors, HTML errors, and minor clarifications. -Final API Version 1 spec. - -<H4>Revision 5 (Draft Version 2)</H4> - -<P>990201 by <A HREF="mailto:smcguire@mit.edu">Scott McGuire</A>. - -<UL> - <LI>Increased API version number to 2. - - <LI>Added enum's defining version numbers. - - <LI>Changes to cc_initialize() to specify how to deal with - different API version numbers. - - <LI>Added description of cc_int32 and cc_uint32 types. - - <LI>Change some cc_int32's to cc_uint32's. - - <LI>Changed way cc_create() will behave when called on an existing - cache. - - <LI>Replaced cc_seq_fetch_NCs() with cc_seq_fetch_NCs_begin(), - cc_seq_fetch_NCs_next(), and cc_seq_fetch_NCs_end(); - - <LI>Replaced cc_seq_fetch_creds() with cc_seq_fetch_creds_begin(), - cc_seq_fetch_creds_next(), and cc_seq_fetch_creds_end(); - - <LI>Replaced enum type references in structs and function - paramenters with cc_int32 references; - - <LI>Replaced int type references in function parameters with - cc_int32; - - <LI>Added return type of cc_int32 to all functions; - - <LI>Removed #ifdef from cred_union structure; - - <LI>Constant definitions and changes to V4Cred_type structure; - - <LI>Removed incorrect const ccache_p * parameters from cc_store() - and cc_remove_cred(); - - <LI>Added CC_NOERROR and CC_BAD_PARM as possible return codes from - all functions (except no CC_BAD_PARM from cc_shutdown() ); - - <LI>Added CC_ERR_CRED_VERSION as possible return code from - cc_open() and cc_create(); - - <LI>Moved infoNC structure definition up to be with rest of - structure definitions; - - <LI>Changed "struct _infoNC" to "infoNC" in parameter type - references. - - <LI>cc_free_principal() and cc_free_name() now take char ** - instead of char * for final parameter. (This change was made - between rev 4a and rev 5, but I'm re-emphasizing it here.) - - <LI>Added Implementation Notes section with requirement that all - functions must be atomic and name requirements for Windows DLL's. - - <LI>Renamed "the proposed changes to this API are" section to - "Ideas for Future Versions" -- but removed all items but one - because they'd all been done. - - <LI>Removed most of the notes about differences with the Win NT/95 - implementation of the API -- the differences have been reconciled. - - <LI>Removed unnecessary and inconsistent italicizing. -</UL> - -<H4>Revsion 5a (Final Version 2)</H4> - -<P>990723 by <A HREF="mailto:smcguire@mit.edu">Scott McGuire</A>. - -<UL> - <LI>cc_create(): Removed text about "expected" form of name. - Removed note about "the alpha version does not do this." - - <LI>cc_destroy(): Clarified that you do not need to call - cc_close() on the cache_pointer after calling this function. - - <LI>Removed note about Windows cc_get_instance() and - cc_set_instance() functions, they are no longer part of the - Windows code! -</UL> - -<H2><A NAME="FutureIdeas"></A>Ideas for Future Versions</H2> - -<UL> - <LI>Define Get/Set functions for all components of _cc_creds? - (This will allow future changes to the data structure to be - transparent to the caller. This also makes backward compatibility - much easier to maintain.) -</UL> - -<P><!-- -----------------------------------------------------------------------------------><!-- type definitions --><!-- -----------------------------------------------------------------------------------><BR> - - -<HR> -<A NAME="TypeDefinitions"></A> - -<H2>Type definitions</H2> - -<PRE>// enums for API versions used in cc_initialize() -enum { - CC_API_VER_1 = 1, - CC_API_VER_2 = 2 -}; - -<A NAME="cc_int32"></A> -// cc_int32 and cc_uint32 are not exactly defined in this API due -// to a lack of standard 32-bit integer size between platforms -// (although there is the C9X standard). -// However, we will place the following constraints: -// -// cc_int32 is a signed integer that is at least 32 bits wide. -// cc_uint32 is an unsigned integer that is at least 32 bits wide - -<A NAME="cc_time_t"></A> -typedef cc_int32 cc_time_t; //see <A HREF="#cc_time_t_Note">notes below</A> -<A NAME="cc_nc_flags"></A> -typedef cc_uint32 cc_nc_flags; - - -<A NAME="opaque_types"></A> -typedef struct opaque_dll_control_block_type* apiCB; -typedef struct opaque_ccache_pointer_type* ccache_p; -typedef struct opaque_credential_iterator_type* ccache_cit; - -// These really are intended to be opaque. All implementations of the cache API must have -// them but what they are is implementation specific. In the case of SGR's implementation, -// the cc_ctx returned available after a call to cc_initialize, is a CCache_ctx class object. The -// code that normally calls the cc_initialize function is straight C, which means the calling -// application doesn't have a chance in hell of manipulating this directly. The API is designed -// so that it does not have to. It does have to pass the pointer to the class around, one reason -// being so that the destructor can eventually be called. - - -<A NAME="typedefCC_Data"></A> -typedef struct _cc_data { - cc_uint32 type; - cc_uint32 length; - unsigned char* data; -} cc_data; - -<A NAME="typedefCC_Cred"></A> -typedef struct _cc_creds { - char* client; /* client's principal identifier */ - char* server; /* server's principal identifier */ - cc_data keyblock; /* session encryption key info */ - cc_time_t authtime; - cc_time_t starttime; - cc_time_t endtime; - cc_time_t renew_till; - cc_uint32 is_skey; /* true if ticket is encrypted in - another ticket's skey */ - cc_uint32 ticket_flags; /* flags in ticket */ - cc_data** addresses; /* addrs in ticket */ - cc_data ticket; /* ticket string itself */ - cc_data second_ticket; /* second ticket, if related to - ticket (via DUPLICATE-SKEY or - ENC-TKT-IN-SKEY) */ - cc_data** authdata; /* authorization data */ -} cc_creds; - - -// use an enumerated type so all callers infer the same meaning -// these values are what krbv4win uses internally. -<A NAME="enumStringToKey_Type"></A> -enum StringToKey_Type { STK_AFS = 0, STK_DES = 1 }; - -enum { MAX_V4_CRED_LEN = 1250 }; - - -// V4 Credentials -<A NAME="typedefV4Cred_type"></A> -enum { - KRB_NAME_SZ = 40, - KRB_INSTANCE_SZ = 40, - KRB_REALM_SZ = 40 -}; - -typedef struct _V4credential { - unsigned char kversion; - char principal[KRB_NAME_SZ+1]; - char principal_instance[KRB_INSTANCE_SZ+1]; - char service[KRB_NAME_SZ+1]; - char service_instance[KRB_INSTANCE_SZ+1]; - char realm[KRB_REALM_SZ+1]; - unsigned char session_key[8]; - cc_int32 kvno; // k95 used BYTE skvno - cc_int32 str_to_key; // k4 infers dynamically, k95 stores; of type enum StringToKey_Type - long issue_date; // k95 called this issue_time - cc_int32 lifetime; // k95 used LONG expiration_time - cc_uint32 address; // IP Address of local host as an unsigned 32-bit integer - cc_int32 ticket_sz; // k95 used BYTE, k4 ktext uses int to hold up to 1250 - unsigned char ticket[MAX_V4_CRED_LEN]; - unsigned long oops; // zero to catch runaways -} V4Cred_type; - -<A NAME="enumCc_cred_vers"></A> -enum cc_cred_vers { - CC_CRED_VUNKNOWN = 0, // For validation - CC_CRED_V4 = 1, - CC_CRED_V5 = 2, - CC_CRED_VMAX = 3 // For validation -}; - -<A NAME="unionCred_ptr_union"></A> -typedef union cred_ptr_union_type { - V4Cred_type* pV4Cred; - cc_creds* pV5Cred; -} cred_ptr_union; - -<A NAME="unionCred_union"></A> -typedef struct cred_union_type { - cc_int32 cred_type; // cc_cred_vers - <A HREF="#unionCred_ptr_union">cred_ptr_union</A> cred; -} cred_union; - -<A NAME="typdefInfoNC"></A> -typedef struct _infoNC { - char* name; - char* principal; - cc_int32 vers; // cc_cred_vers -} infoNC;</PRE> - -<H4>The cc_data structure</H4> - -<P>The cc_data structure is used to store the following elements: - -<UL> - <LI>keyblock - - <LI>addresses - - <LI>ticket (and second_ticket) - - <LI>authorization data -</UL> - -<P>For cc_creds.ticket and cc_creds.second_ticket, the cc_data.type -field MUST be zero. For the cc_creds.addresses, cc_creds.authdata, -and cc_data.keyblock, the cc_data.type field should be the address -type, authorization data type, and encryption type, as defined by the -Kerberos V5 protocol definition. - -<H4><A NAME="cc_time_t_Note"></A>cc_time_t</H4> - -<P>The cc_time_t fields are used to represent time. The time must be -stored as the number of seconds since midnight GMT on January 1, -1970. - -<H4>Principal names</H4> - -<P>Principal names are stored as C strings in this API. The C strings -may contain UTF-8 encoded strings for internationalization -purposes.<BR> - - -<HR> -<A NAME="ErrorCodeDefinitions"></A> - -<H2>Error Codes Definition</H2> - -<P><TABLE BORDER=1> - <TR> - <TD> - <P>0 - </TD><TD> - <P>CC_NOERROR - </TD><TD> - <P>"Successful return" - </TD></TR> - <TR> - <TD> - <P>1 - </TD><TD> - <P>CC_BADNAME - </TD><TD> - <P>"Bad credential cache name format" - </TD></TR> - <TR> - <TD> - <P>2 - </TD><TD> - <P>CC_NOTFOUD - </TD><TD> - <P>"Matching credential not found" - </TD></TR> - <TR> - <TD> - <P>3 - </TD><TD> - <P>CC_END - </TD><TD> - <P>"End of credential cache reached" - </TD></TR> - <TR> - <TD> - <P>4 - </TD><TD> - <P>CC_IO - </TD><TD> - <P>"Credentials cache I/O operation failed" - </TD></TR> - <TR> - <TD> - <P>5 - </TD><TD> - <P>CC_WRITE - </TD><TD> - <P>"Error writing to credentials cache file" - </TD></TR> - <TR> - <TD> - <P>6 - </TD><TD> - <P>CC_NOMEM - </TD><TD> - <P>"No memory" - </TD></TR> - <TR> - <TD> - <P>7 - </TD><TD> - <P>CC_FORMAT - </TD><TD> - <P>"Corrupted credentials cache" - </TD></TR> - <TR> - <TD> - <P>8 - </TD><TD> - <P>CC_LOCKED - </TD><TD> - <P>"The credentials cache or NC is locked" - </TD></TR> - <TR> - <TD> - <P>9 - </TD><TD> - <P>CC_BAD_API_VERSION - </TD><TD> - <P>"Unsupported API version" - </TD></TR> - <TR> - <TD> - <P>10 - </TD><TD> - <P>CC_NO_EXIST - </TD><TD> - <P>"Credentials cache or NC does not exist" - </TD></TR> - <TR> - <TD> - <P>11 - </TD><TD> - <P>CC_NOT_SUPP - </TD><TD> - <P>"Function not supported" - </TD></TR> - <TR> - <TD> - <P>12 - </TD><TD> - <P>CC_BAD_PARM - </TD><TD> - <P>"Bad Paramter Passed" - </TD></TR> - <TR> - <TD> - <P>13 - </TD><TD> - <P>CC_ERR_CACHE_ATTACH - </TD><TD> - <P>"Failed to attach cache" - </TD></TR> - <TR> - <TD> - <P>14 - </TD><TD> - <P>CC_ERR_CACHE_RELEASE - </TD><TD> - <P>"Failed to release cache" - </TD></TR> - <TR> - <TD> - <P>15 - </TD><TD> - <P>CC_ERR_CACHE_FULL - </TD><TD> - <P>"Cache FULL" - </TD></TR> - <TR> - <TD> - <P>16 - </TD><TD> - <P>CC_ERR_CRED_VERSION - </TD><TD> - <P>"Wrong Cred Version" - </TD></TR> -</TABLE> - -<P> -<HR> -<A NAME="ImplementationNotes"></A> - -<H2>Implementation Notes</H2> - -<H4>All functions are atomic</H4> - -<P>All Credentials Cache API functions must be atomic. - -<P><B>Windows</B> - -<P>DLLs should be named KrbCC16.dll and KrbCC32.dll. - -<P> -<HR> -<A NAME="FunctionDefinitions"></A> - -<H2>Function definitions</H2> - -<P><A NAME="MainCacheFunctions"></A> - -<H3>Main Cache Functions</H3> - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_initialize --><!-- -----------------------------------------------------------------------------------> - - -<P><A NAME="cc_initialize"></A> - -<H4>cc_initialize</H4> - -<PRE>cc_int32 cc_initialize(apiCB** cc_ctx, cc_int32 api_version, cc_int32* api_supported, char** vendor)</PRE> - -<P>This function performs any initialization required by the -<I>API</I>. It must be called before any other function in the -<I>API</I> is called. The cc_ctx returned by this function must be -passed to all other <I>API</I> functions as the first argument. - -<P>The application must pass in the maximum version number of the API -it supports in the <B>api_version</B> parameter. - -<P>If <B>api_supported</B> non-NULL, then cc_initialize will store -the maximum API version number supported by the library implementing -the API there. - -<P>If the version requested by <B>api_version</B> is not equal to the -version supported by the library, CC_BAD_API_VERSION will be returned -as the error code (along with the version the library does support in -<B>api_supported</B>) and cc_initialize should not allocate any -memory. - -<P>If the <B>vendor</B> is non-NULL, then cc_initialize will store a -pointer to a read/only C string which contains a string describing -the vendor which implemented the credentials cache <I>API</I>. - -<P>Possible error codes: CC_NOERROR, CC_NOMEM, CC_BAD_API_VERSION, -CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_shutdown --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_shutdown"></A> - -<H4>cc_shutdown</H4> - -<PRE>cc_int32 cc_shutdown(apiCB** cc_ctx)</PRE> - -<P>This function performs any cleanup required by the <I>API</I>. -cc_ctx will be NULL on return. The application program must call -cc_initialize() again before making any credentials cache <I>API</I> -calls. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_get_change_time --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_get_change_time"></A> - -<H4>cc_get_change_time</H4> - -<PRE>cc_int32 cc_get_change_time(apiCB* cc_ctx, cc_time_t* time)</PRE> - -<P>This function returns the time of the most recent change for the -entire cache. There is ONE timestamp maintained for the entire cache. -By maintaining a local copy the caller can deduce whether "something -changed" or not. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_NOMEM, -CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_get_NC_info --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_get_NC_info"></A> - -<H4>cc_get_NC_info</H4> - -<PRE>cc_int32 cc_get_NC_info(apiCB* cc_ctx, infoNC*** ppNCi)</PRE> - -<P>cc_get_NC_info() is a wrapper for cc_seq_fetch_NCs(), -cc_get_name() cc_get_cred_version(), and cc_get_principal(). It -returns all the information needed to uniquely identify each NC in -the cache (name and cred_version) and the associated principal. -Specifically it returns a null terminated list of pointers to infoNC -structs. Each infoNC struct contain a pointer to the NC's name, a -pointer to the the principal associated with the NC, and the version -number (as an enumerated type) of the credentials stored in this NC. - -<P>The ppNCi (the entire data structure) aquired by this routine -should be freed with cc_free_NC_info(). - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_NOMEM, -CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_open --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_open"></A> - -<H4>cc_open</H4> - -<PRE>cc_int32 cc_open(apiCB* cc_ctx, const char* name, cc_int32 cred_vers, cc_uint32 cc_flags, - ccache_p** ccache_pointer)</PRE> - -<P>Opens an already exising NC identified by both <B>name</B>, and -<B>cred_vers</B>. It fills in the parameter **ccache_pointer with a -pointer to the NC. - -<P>The list of cache names, principals, and credentials versions may -be retrieved via cc_seq_fetch_NCs(), cc_get_name(), -cc_get_cred_version(), & cc_get_principal() OR via -cc_get_NC_info(). - -<P>Possible error codes: CC_NOERROR, CC_BADNAME, CC_NO_EXIST, -CC_NOMEM, CC_ERR_CRED_VERSION, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_create --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_create"></A> - -<H4>cc_create</H4> - -<PRE>cc_int32 cc_create(apiCB* cc_ctx, const char* name, const char* principal, - cc_int32 cred_vers, cc_uint32 cc_flags, ccache_p** ccache_pointer)</PRE> - -<P>Create a new NC. The NC is uniquely identified by the combination -of it's name and the "cc_creds_vers" (i.e. which credentials version -it holds). The principal given is also associated with the NC. A NULL -<B>name</B> is not allowed (and CC_BADNAME should be returned if one -is passed in). If <B>name</B> is non-null and there is already a NC -named <B>name</B>, all credentials in the cache are removed, and -handle for the existing cache is returned. If there is already a NC -named name, all existing handles for this cache remain valid. The NC -is created with a primary principal specified by <B>principal</B>. - -<P><I>(Removed text about the "expected" form of the NC name.)</I> - -<P>An NC is intended to hold credentials for a single principal in a -single realm, and for a single credentials version (i.e. V4 or V5). -The cache can contain credentials for other credential versions, -other realms, and even other principals, but each in a separate NC. -This rule will allow callers that can only handle a single principal -in a single realm to continue to work by dealing with only one NC. -Callers that can deal with multiple principals, multiple realms, -and/or multiple credentials versions can do so by dealing with -multiple NCs. By doing it this way, the callers that are able to -handle multiple principals, realms, and/or versions can do so without -interfering with "differently abled" code. - -<P>The list of cache names, principals, & cred_versions may be -retrieved via cc_get_NC_info(). - -<P>Possible error codes: CC_NOERROR, CC_BADNAME, CC_BAD_PARM, -CC_NO_EXIST, CC_NOMEM, CC_ERR_CRED_VERSION - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_close --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_close"></A> - -<H4>cc_close</H4> - -<PRE>cc_int32 cc_close(apiCB* cc_ctx, ccache_p** ccache_pointer)</PRE> - -<P>Close the NC. The <B>ccache_pointer</B> related memory is -deallocated, and ccache_pointer is set to NULL before being returned -to caller. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_destroy --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_destroy"></A> - -<H4>cc_destroy</H4> - -<PRE>cc_int32 cc_destroy(apiCB* cc_ctx, ccache_p** ccache_pointer)</PRE> - -<P>Destroy the NC pointed to by <B>ccache_pointer</B>. The -<B>ccache_pointer</B> related memory is deallocated, and -ccache_pointer is set to NULL before being returned to caller. The -caller does not need to call cc_close() on the <B>cache_pointer</B> -afterwards. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_seq_fetch_NCs --><!-- -----------------------------------------------------------------------------------><BR> - - - -<P><A NAME="cc_seq_fetch_NCs_begin"></A> - -<H4>cc_seq_fetch_NCs_begin</H4> - -<PRE>cc_int32 cc_seq_fetch_NCs_begin(apiCB* cc_ctx, ccache_cit** itNCs)</PRE> - -<P>Used to allocate memory and initialize the iterator *itNCs. Use -cc_seq_fetch_NCs_end() to deallocate the memory used by *itNCs. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM, -CC_NOMEM - -<H4><A NAME="cc_seq_fetch_NCs_next"></A></H4> - -<H4>cc_seq_fetch_NCs_next</H4> - -<PRE>cc_int32 cc_seq_fetch_NCs_next(apiCB* cc_ctx, ccache_p** ccache_pointer, ccache_cit* itNCs)</PRE> - -<P>Used to sequentially open every NC in the cache. - -<P>Ccache_pointer must be a pointer to a ccache_p*. The -ccache_pointer returned may be used to get information about the NC -by calling cc_get_name(), cc_get_cred_version(), and -cc_get_principal(). Ccache_pointer's returned must be freed via -cc_close() between calls to cc_seq_fetch_NCs_next(). - -<P>itNCs must be a pointer to a ccache_cit* variable provided by the -calling application and which is used by cc_seq_fetch_NCs_next() to -determine the next NC to return. It must have been initialized by -cc_seq_fetch_NCs_begin(). - -<P>If changes are made to the credentials cache while it iterator is -being used, it must return at least the intersection, and at most the -union, of the set of NC's that were in the cache when the iteration -began and the set of NC's that are in the cache when it ends. - -<P>When the last NC in the sequence is returned, the return code from -cc_seq_fetch_NCs_next() will be CC_END. - -<P>Possible error codes: CC_NOERROR, CC_END, CC_NO_EXIST. -CC_BAD_PARM, CC_NOMEM - -<H4> </H4> - -<H4><A NAME="cc_seq_fetch_NCs_end"></A></H4> - -<H4>cc_seq_fetch_NCs_end</H4> - -<PRE>cc_int32 cc_seq_fetch_NCs_end(apiCB* cc_ctx, ccache_cit** itNCs)</PRE> - -<P>Deallocates the memory used by *itNCs, and sets *itNCs to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P> - -<P><A NAME="NCFunctions"></A> - -<H3>NC Functions</H3> - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_get_name --><!-- -----------------------------------------------------------------------------------><A NAME="cc_get_name"></A> - - -<H4>cc_get_name</H4> - -<PRE>cc_int32 cc_get_name(apiCB* cc_ctx, const ccache_p* ccache_pointer, char** name)</PRE> - -<P>cc_get_name() returns the name of the NC indicated by -ccache_pointer. The name can be used in cc_open() or cc_create(). The -combination of the name and the credentials version uniqeuly identify -an NC. The returned name should be freed via cc_free_name(). - -<P>Possible error codes: CC_NOERROR, CC_NOMEM, CC_NO_EXIST, -CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_get_cred_version --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_get_cred_version"></A> - -<H4>cc_get_cred_version</H4> - -<PRE>cc_int32 cc_get_cred_version(apiCB* cc_ctx, const ccache_p* ccache_pointer, cc_int32* cred_vers)</PRE> - -<P>cc_get_cred_version() returns one of the enumerated type -cc_cred_vers in cred_vers. The expected values are CC_CRED_V4, or -CC_CRED_V5. The combination of the name and the credentials version -uniquely identify an NC. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_set_principal --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_set_principal"></A> - -<H4>cc_set_principal</H4> - -<PRE>cc_int32 cc_set_principal(apiCB* cc_ctx, const ccache_p* ccache_pointer, const cc_int32 cred_vers, - const char* principal)</PRE> - -<P>Set the primary principal for the NC indicated by ccache_pointer. -This is the complement to cc_get_principal(). - -<P>cred_vers is used as a double check. - -<P>principal points to a null terminated string that will be copied -into the NC. This new principal will be returned if you call -cc_get_principal() for this NC. - -<P>Possible error codes: CC_NOERROR, CC_NOMEM, CC_NO_EXIST, -CC_ERR_CRED_VERSION, CC_BAD_PARM<BR> - - - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_get_principal --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_get_principal"></A> - -<H4>cc_get_principal</H4> - -<PRE>cc_int32 cc_get_principal(apiCB* cc_ctx, const ccache_p* ccache_pointer, char** principal)</PRE> - -<P>Return the primary principal for the NC that was set via -cc_create() or cc_set_principal(). The returned principal should be -freed via cc_free_principal() . - -<P>Possible error codes: CC_NOERROR, CC_NOMEM, CC_NO_EXIST, -CC_BAD_PARM<BR> - - - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_store --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_store"></A> - -<H4>cc_store</H4> - -<PRE>cc_int32 cc_store(apiCB* cc_ctx, ccache_p* ccache_pointer, const <A HREF="#unionCred_union">cred_union</A> cred)</PRE> - -<P>Store (make a copy of) <B>cred</B> in the NC indicated by -<B>ccache_pointer</B>. - -<P>A cred_union contains a cred_type indicator and a cred_ptr_union. -A cred_ptr_union can contain either a V4Cred_type pointer or a -cc_creds (V5 creds) pointer. Cred_type indicates which type of -pointer is in the cred_ptr_union. This also allows the <I>API</I> to -enforce the credentials version declared in cc_create() or cc_open(). - - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_ERR_CACHE_FULL, -CC_ERR_CRED_VERSION, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_remove_cred --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_remove_cred"></A> - -<H4>cc_remove_cred</H4> - -<PRE>cc_int32 cc_remove_cred(apiCB* cc_ctx, ccache_p* ccache_pointer, const <A HREF="#unionCred_union">cred_union</A> cred)</PRE> - -<P>Removes the credential <B>cred</B> from <B>ccache_pointer</B>. The -credentials in the NC indicated by ccache_pointer are searched to -find a matching credential. If found, that credential is removed from -the NC. The cred parameter is not modified and should be freed via -cc_free_creds(). It is legitimate to call this function during a -sequential fetch, and the deletion of a credential already returned -by cc_seq_fetch_creds() should not disturb sequence of credentials -returned by cc_seq_fetch_creds(). - -<P>Use of cred_union is the same as is explained in cc_store(). - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_NOTFOUND, -CC_ERR_CRED_VERSION, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_seq_fetch_creds --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_seq_fetch_creds_begin"></A> - -<H4>cc_seq_fetch_creds_begin</H4> - -<PRE>cc_int32 cc_seq_fetch_creds_begin(apiCB* cc_ctx, const ccache_p* ccache_pointer, ccache_cit** itCreds)</PRE> - -<P>Allocates memory for and initializes *itCreds. This memory must be -deallocated using cc_seq_fetch_creds_end(). - -<P>Ccache_pointer must be a valid pointer to the NC containing the -creds to be returned by the iterator. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM, -CC_NOMEM - -<P> - -<P><A NAME="cc_seq_fetch_creds_next"></A> - -<H4>cc_seq_fetch_creds_next</H4> - -<PRE>cc_int32 cc_seq_fetch_creds_next(apiCB* cc_ctx, cred_union** cred, ccache_cit* itCreds)</PRE> - -<P>cc_seq_fetch_creds_next() is used to sequentially read every set -of credentials in an NC. The NC has been indicated in the call to -cc_seq_fetch_creds_begin(). - -<P>itCreds must be a pointer to a ccache_cit* variable provided by -the calling application and which is used by -cc_seq_fetch_creds_next() to determine the next cached credential to -return. The ccache_cit* variable must be initialized by calling -cc_seq_fetch_creds_begin(). - -<P>The credentials are filled into the cred_union pointed to by -creds. Note that the cred_union contains elements which are -dynamically allocated, so must be freed using cc_free_creds() between -calls to cc_seq_fetch_creds_next(). - -<P>If changes are made to the NC while it iterator is being used, it -must return at least the intersection, and at most the union, of the -set of credentials that were in the NC when the iteration began and -the set of credentials that are in the NC when it ends. - -<P>When the last credential in the sequence is returned, the return -code from cc_seq_fetch_creds_next() will be CC_END. - -<P>Possible error codes: CC_NOERROR, CC_END, CC_NO_EXIST, -CC_BAD_PARM, CC_NOMEM - -<P> - -<P><A NAME="cc_seq_fetch_creds_end"></A> - -<H4>cc_seq_fetch_creds_end</H4> - -<PRE>cc_int32 cc_seq_fetch_creds_end(apiCB* cc_ctx, ccache_cit** itCreds)</PRE> - -<P>Deallocates memory used by *itCreds and sets *itCreds to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_lock_request --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_lock_request"></A> - -<H4>cc_lock_request</H4> - -<PRE>cc_int32 cc_lock_request(apiCB* cc_ctx, const ccache_p* ccache_pointer, cc_int32 lock_type)</PRE> - -<DL> - <DD>99/02/11 - smcguire - - <DD><B>As of this date there is no locking in the Win NT/95 - or Machintosh implementations. The description below may not be - completely accurate as to how this function should be - implemented.</B> -</DL> - -<P>This function is currently NOT IMPLEMENTED. All functions attach -to the cache, take action, and detach from the cache before returning -to the caller. - -<P>This function will lock or unlock the NC based on the argument -value of lock_type: - -<PRE> CC_LOCK_UNLOCK 1 Unlock the NC - CC_LOCK_READER 2 Lock the NC for reading - CC_LOCK_WRITER 3 Lock the NC for writing - - CC_LOCK_NOBLOCK 16 Don't block, but return an error code if - the request cannot be satisfied. - </PRE> - -<P>Locking is done on a per-thread basis. At most one thread may have -the credentials locked for writing; if so, there must not be any -threads that have the credentials locked for reading. - -<P>Multiple threads may have the cache locked for reading, as long as -there is not a writer lock asserted on the cache. - -<P>If a thread has a cache locked for reading, that lock may be -upgraded to a writer lock by calling cc_lock_request() with a -lock_type of CC_LOCK_WRITER. If a thread has the cache locked for -reading or writing, a request to cc_lock_request() for a reader or -writer lock, respectively, is a no-op. If a thread does not have the -cache locked, and calls cc_lock_request() with a lock_type of -CC_LOCK_UNLOCK, this is also a no-op. - -<P>A request for CC_LOCK_READER and CC_LOCK_WRITER may be made -non-blocking by logical or'ing the value CC_LOCK_NOBLOCK. In that -case, if it is not possible to satisfy the lock request, the error -CC_LOCKED will be returned. - -<P> - -<P><A NAME="LiberationFunctions"></A> - -<H3>Liberation Functions</H3> - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_free_principal --><!-- -----------------------------------------------------------------------------------><A NAME="cc_free_principal"></A> - - -<H4>cc_free_principal</H4> - -<PRE>cc_int32 cc_free_principal(apiCB* cc_ctx, char** principal)</PRE> - -<P>This function frees the <B>principal</B> returned by -cc_get_principal() and sets *principal to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_free_name --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_free_name"></A> - -<H4>cc_free_name</H4> - -<PRE>cc_int32 cc_free_name(apiCB* cc_ctx, char** name)</PRE> - -<P>This function frees the <B>name</B> returned by cc_get_name() and -sets *name to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_free_creds --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_free_creds"></A> - -<H4>cc_free_creds</H4> - -<PRE>cc_int32 cc_free_creds(apiCB* cc_ctx, cred_union** creds)</PRE> - -<P>This function frees all storage associated with creds returned by -cc_seq_fetch_creds() and sets the creds pointer to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<P><!-- -----------------------------------------------------------------------------------><!-- cc_free_NC_info --><!-- -----------------------------------------------------------------------------------><BR> - -<A NAME="cc_free_NC_info"></A> - -<H4>cc_free_NC_info</H4> - -<PRE>cc_int32 cc_free_NC_info(apiCB* cc_ctx, infoNC*** ppNCi)</PRE> - -<P>This routine frees all storage aquired by cc_get_NC_info() and -sets ppNCi to NULL. - -<P>Possible error codes: CC_NOERROR, CC_NO_EXIST, CC_BAD_PARM - -<!-- Begin MIT-use only web reporting counter --> - <IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT=""> -<!-- End MIT-use only web reporting counter --> -</BODY></HTML> |