[1846] in Kerberos_V5_Development
Krb5 Ccache DLL proposal
daemon@ATHENA.MIT.EDU (Theodore Ts'o)
Fri Oct 4 12:34:14 1996
Date: Fri, 4 Oct 1996 12:33:15 -0400
From: "Theodore Ts'o" <tytso@MIT.EDU>
To: "Theodore Y. Ts'o" <tytso@MIT.EDU>, mikec@geek.grf.ov.com,
harryc@cam.ov.com, pbh@MIT.EDU, krbdev@MIT.EDU, dosdev@MIT.EDU
Based on the comments I received, here's the second draft of a DLL
specification for the Krb5 Credentials Cache functions. Have at it.....
- Ted
Type definitions
================
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 endime;
cc_time_t renew_till;
int is_skey; /* true if ticket is encrypted in
another ticket's skey */
cc_int32 ticket_flags; /* flags in ticket */
cc_data FAR * FAR *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 FAR * FAR *authdata; /* authorization data */
} cc_creds;
typedef struct _cc_data {
cc_int32 type;
int length;
unsigned char FAR *contents;
} cc_data;
Note: The cc_data structure is used to store the following elements:
* keyblock
* addresses
* ticket (and second_ticket)
* authorization data
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.
Error Codes Definition
======================
0) CC_NOERROR "Successful return"
1) CC_BADNAME "Bad format in credential cache name"
2) CC_NOTFOUND "Matching credential not found"
3) CC_END "End of credential cache reached"
4) CC_IO "Credentials cache I/O operation failed"
5) CC_WRITE "Error writing to credentials cache file"
6) CC_NOMEM "No memory"
7) CC_FORMAT "Corrupted credentials cache"
8) CC_LOCKED "The credentials cache is locked"
9) CC_BAD_API_VERSION "Unsupported API version"
10) CC_NO_EXIST "Credentials cache does not exist"
Function definitions
====================
cc_initailize(void **cc_ctx, int api_version)
This function performs any initialization required by the DLL. It
must be called before any other functions in the DLL is called. The
cc_ctx returned by this function should be passed to all other DLL
functions as the first argument.
The api_version field must be CC_API_VER_1 (which is #defined to be 1).
Possible error codes: CC_NOMEM, CC_BAD_API_VERSION
---------------------------------------------
cc_shutdown(void *cc_ctx)
This function performs any cleanup required by the DLL. No DLL
functions should be called with the passed-in <cc_ctx> argument after
this function returns. The application prorgram must call
cc_initialize() again before making any credentails cache DLL calls.
Possible error codes: none
---------------------------------------------
cc_open(void *cc_ctx, char *name, void **handle)
Opens an already credentials cache named <name>, and fills in the
parameter **handle with a handle to the credentials cache.
Possible error codes: CC_BADNAME, CC_NO_EXIST, CC_NOMEM
---------------------------------------------
cc_create(void *cc_ctx, char *name, char *principal, void **handle)
Create a new credentials cache; if the <name> is NULL, create it with
a unique name. If <name> is non-null and there is already a
credentials cache named <name>, the old credentials cache is destroyed
and a new one created with that name. The credentials cache is
created with a primary principal specified by <principal>.
Possible error codes: CC_BADNAME, CC_NOMEM
---------------------------------------------
cc_close(void *cc_ctx, void *handle)
Close the credentials cache. The <handle> is dellocated, and is no
longer valid after this call returns.
Possible error codes: none
---------------------------------------------
cc_destroy(void *cc_ctx, void *handle)
Destroy the credentials cache pointed to by <handle>. The <handle> is
dellocated, and is no longer valid after this call returns.
Possible error codes: none
---------------------------------------------
cc_store(void *cc_ctx, void *handle, cc_creds *creds)
Store <cred> into the ccache pointed to by <handle>.
Possible error codes: none
---------------------------------------------
cc_get_principal(void *cc_ctx, void *handle, char **principal)
Return the primary principal for the credentials cache. The principal
may be freed using free(). (XXX is this a good idea? Should we
specify our own freeing function? I know windows has more than one
kind of memory, with different freeing functions.)
Possible error codes: CC_NOMEM
---------------------------------------------
cc_start_seq_fetch(void *cc_ctx, void *handle, void **cursor)
Prepares to sequentially read every set of cached credentials.
Requires that <handle> identifies a valid credentials cache.
<cursor> is filled in with a cursor to be used in calls to
cc_seq_fetch()
Possible error codes: CC_NOMEM
---------------------------------------------
cc_seq_fetch(void *cc_ctx, void *handle, cc_creds * creds, void *cursor)
Fetches the next entry from <handle>, returning its values in <creds>,
and updates <cursor> for the next request. Requires that <handle>
identifies a valid credentials cache and <cursor> be a cursor returned
by cc_start_seq_fetch() or a subsequent call to cc_seq_fetch().
Possible error codes: CC_NOMEM, CC_END
---------------------------------------------
cc_end_seq_fetch(void *cc_ctx, void *handle, void *cursor)
Finishes sequential processing mode and invalidates <cursor>.
Possible error codes: none
---------------------------------------------
cc_remove_cred(void *cc_ctx, void *handle, cc_creds *cred)
Removes the credential <cred> from <handle>. It is legitimate to call
this function during a sequential fetch, and the deletion of a
credential already returned by cc_seq_fetch() should not disturb
sequence of credentials returned by cc_seq_fectch.
---------------------------------------------
cc_free_cred(void *cc_ctx, cc_creds *cred)
Releases any memory used by the credential <cred>. The pointer <cred>
should not be used after this function returns.
---------------------------------------------
cc_lock_request(void *cc_ctx, void *handle, int lock_type)
This function will lock or unlock the credentials cache based on the
argument value of lock_type:
CC_LOCK_UNLOCK 1 Unlock the credentials cache
CC_LOCK_READER 2 Lock the credentials cache for reading
CC_LOCK_WRITER 3 Lock the credentials cache for writing
CC_LOCK_NOBLOCK 16 Don't block, but return an error code if
the request cannot be satisfied.
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 which have the credentials locked for reading.
Multiple threads may have the cache locked for reading, as long as
there is not a writer lock asserted on the cache.
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 lcoked 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.
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.
