[1800] in Kerberos_V5_Development
Krb5 Ccache DLL proposal
daemon@ATHENA.MIT.EDU (Theodore Y. Ts'o)
Thu Sep 26 19:17:56 1996
Date: Thu, 26 Sep 1996 19:17:41 -0400
From: "Theodore Y. Ts'o" <tytso@MIT.EDU>
To: mikec@geek.grf.ov.com, harryc@cam.ov.com, pbh@MIT.EDU
Cc: krbdev@MIT.EDU, dosdev@MIT.EDU
Hi there,
Sorry it's taken me so long to get this done. I've had a lot of
other fires demanding my attention at MIT this past week or two.
In any case, per our previous conversation at the MIT/OV
meeting, here's a draft proposal of a Windows DLL interface for
credentials cache handling function.
For those who were not at our meeting, the idea is to promulgate
this interface as the standard way of having multiple Kerberos
implementations (including some which are not based on the MIT codebase)
to have access a single credentials cache. This is very important for
single signon if (for example) a user has one application which uses the
MIT Kerberos V5 DLL, and another application which uses the Cybersafe
Krb5 DLL or the Locos DLL. Some of these implementation store the
credentials in incompatible methods, and it would very poor if the user
had to type in their password once for each application.
Note that this DLL is a ***draft***. I present it knowing that
there are probably things which I've overlooked, and hoping for
comments. People should NOT try to implement code based on this
proposal just yet, as it is still subject to change (and improvement).
- Ted
Here's the first draft of a DLL specification for the Krb5 Credentials
Cache functions.
Type definitions
================
typedef struct _cc_creds {
char *client; /* client's principal identifier */
char *server; /* server's principal identifier */
cc_keyblock 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_typed_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_typed_data FAR * FAR *authdata; /* authorization data */
} cc_creds;
typedef struct _cc_keyblock {
cc_int32 enctype;
int length;
unsigned char FAR *contents;
} krb5_keyblock;
typedef struct _cc_data {
int length;
unsigned char FAR *data;
} cc_data;
typedef struct _cc_typed_data {
cc_int32 type;
int length;
unsigned FAR *contents;
} cc_typed_data;
Error Codes Definition
======================
0) CC_NOERROR "Successful return"
1) CC_BADNAME "Bad format of credential cache"
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"
Function definitions
====================
cc_open(char *name, void **handle)
Opens an already credentials cache named <name>, and fills in the
parameter **handle with a handle to the credentials cache.
cc_create(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>.
cc_close(void *handle)
Close the credentials cache. The <handle> is dellocated, and is no
longer valid after this call returns.
cc_destroy(void *handle)
Destroy the credentials cache pointed to by <handle>. The <handle> is
dellocated, and is no longer valid after this call returns.
cc_store(void *handle, cc_creds *creds)
Store <cred> into the ccache pointed to by <handle>.
cc_get_principal(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.)
cc_start_seq_fetch(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()
cc_seq_fetch(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().
%Errors: error code if no more cache entries.
cc_end_seq_fetch(void *handle, void *cursor)
Finishes sequential processing mode and invalidates <cursor>.
cc_remove_cred(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_lock(void *handle)
Lock the credentials cache so that other processes can not modify it.
cc_unlock(void *handle)
Unlock the credentials cache so that other processes can modify it.
It is not necessary to lock or unlock a credential cache before
reading or modifying the ccache. If the credentials cache is
unlocked, ccache primitives should lock and unlock the credentials
cache upon entry and exit. If the application will be doing many
credentials cache operations, however, it will be more efficient to
call cc_lock() and cc_unlock().
