r18022@luminous: jaltman | 2006-05-19 05:18:37 -0400

 Updates of portable CCAPI sources.   All code compiles.
 
 
 r18025@luminous:  jaltman | 2006-05-20 23:48:39 -0400
 Construct an outline of a sample platform specific main.c
 
 Add ccs_serv_cleanup() routine.  Currently does nothing.
 
 Correct field names used within the authorization check.
 
 
 r18026@luminous:  jaltman | 2006-05-22 02:25:43 -0400
 More byte order conversions in the server operations code.
 
 
 
 r18027@luminous:  jaltman | 2006-05-22 13:12:49 -0400
 Source files containing common routines used by both 
 the client and the server.
 
 
 
 r18028@luminous:  jaltman | 2006-05-22 13:17:07 -0400
 Move msg.c and marshall.c to common library.
 
 Add dllmain.c which contains the Windows DllMain() entry 
 point.  This must be moved later to a Windows specific 
 directory.
 
 Cleanup type usage and function name references.  
 
 All that is missing now from the client DLL is a definition
 of cci_perform_rpc() which is the entry point to the IPC
 routine.
 
 
 r18029@luminous:  jaltman | 2006-05-22 13:18:27 -0400
 Move generic list functions to common/generic_lists.c
 so they can be used by both the client dll and the server.
 
 Fix type utilization in serv_ops.c
 
 
 r18083@luminous:  jaltman | 2006-06-05 13:49:34 -0400
 improved error handling
 
 
 r18094@luminous:  jaltman | 2006-06-09 10:42:04 -0400
 * corrections to windows rpc layer
 
 * corrections to network byte order conversions
 
 
 r18095@luminous:  lxs | 2006-06-09 17:46:24 -0400
 cci_msg_retrieve_blob(): changed argument 4 from void** to char** 
 to suppress the warnings from gcc.
 
 r18096@luminous:  lxs | 2006-06-09 17:55:32 -0400
 moved enum cc_list_type to generic_lists.h to avoid "incomplete enum" 
 warnings when compiling generic_lists.c
 
 r18097@luminous:  lxs | 2006-06-09 17:56:15 -0400
 Removed ancient Metrowerks tests from public headers.
 
 r18098@luminous:  lxs | 2006-06-09 17:57:20 -0400
 Include string.h to get memcpy, strlen, etc on BSD OSes.
 
 r18099@luminous:  lxs | 2006-06-09 17:59:36 -0400
 Added Mac OS X project file and Mach-IPC support code
 
 
 r18106@luminous:  jaltman | 2006-06-12 09:56:31 -0400
 remove duplicate header file and obsolete source file
 
 
 r18193@luminous:  jaltman | 2006-06-22 12:57:14 -0400
 This commit updates lib/krb5/ccache/ccapi to support CCAPI Version 3
 and above.  Specify -DUSE_CCAPI_V3=1 when compiling to use CCAPI Version 3
 
 
 r18194@luminous:  jaltman | 2006-06-22 12:58:37 -0400
 Fix parameter name in cc_credentials_iterator_t next()
 
 
 r18195@luminous:  jaltman | 2006-06-22 12:59:08 -0400
 Add missing header
 
 
 r18196@luminous:  jaltman | 2006-06-22 13:11:37 -0400
 Use the old exported names for setup and shutdown
 
 
 r18197@luminous:  jaltman | 2006-06-22 13:18:14 -0400
 krb5_stdccv3_setup is ok
 
 

=== Please enter your commit message above this line ===

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@18200 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 156 insertions, 0 deletions

diff --git a/src/lib/ccapi/doc/implementation-notes.txt b/src/lib/ccapi/doc/implementation-notes.txt
new file mode 100644
index 000000000..e6150fb23
--- /dev/null
+++ b/src/lib/ccapi/doc/implementation-notes.txt
@@ -0,0 +1,156 @@
+The following are notes describing the requirements of the Platform

+Specific code necessary for constructing a Portable CCAPI.

+

+Directory structure:

+

+ lib/ccapi/client    - platform independent client library

+ lib/ccapi/common    - platform independent common library

+ lib/ccapi/include   - platform independent header files

+ lib/ccapi/mac       - macosx specific headers, libraries, executables

+ lib/ccapi/server    - platform independent server library

+ lib/ccapi/windows   - windows specific headers, libraries, executables

+

+

+Platform Independent Design:

+

+The functionality of the Portable CCAPI is implemented in the platform

+independent libraries.   The common library encapsulates the functions

+for managing generic lists, iterators, and messages as well as routines

+formarshalling and unmarshalling.  The client library provides the

+client side routines for issuing requests to the ccapi server minus the

+platform dependent glue required for shared library initialization,

+cleanup, and interprocess communications.  The server library provides

+server side functionality for managing credential cache collections,

+caches, credentials, iterators, and their handles minus the platform

+dependent glue for process initialization, interprocess communication,

+session security, and critical section enforcement.

+

+

+Platform Dependent Design Requirements:

+

+The platform dependent code is responsible for producing a shared

+client library:

+

+ + the shared library is built from cc_client.lib and cc_common.lib plus

+   platform dependent glue

+

+   - [windows] link cc_client.lib and cc_common.lib with platform

+     dependent routines and export list (.def) to produce

+     krbcc32.{lib,dll}

+

+ + initialization and cleanup

+

+   - [windows] provide DllMain entry point providing Process and Thread

+     attachment and detachment routines

+

+ + implement cci_perform_rpc() function used by cc_client.lib

+     cc_int32 cci_perform_rpc(cc_msg_t *request, cc_msg_t **response)

+

+   - cci_perform_rpc() takes an input request cc_msg_t object, flattens

+     it with cci_msg_flatten() and sends the contents of unsigned char

+     buffer request->flat of length request->flat_len to the server

+     utilizing a platform specific interprocess communication method.

+

+   - upon IPC success, cci_perform_rpc() unflattens the response buffer

+     with cci_msg_unflatten() and returns the new cc_msg_t response

+     object to the caller.

+

+   - cci_perform_rpc() is responsible for performing any necessary

+     session security management.  For example, on Windows the Logon

+     Provider executes under the local machine's "SYSTEM" account within

+     session 0 and not under the account of the user that is logging in

+     nor within the session the user's desktop and applications will be

+     running within.  It is the responsibility of cci_perform_rpc() and

+     the platform dependent IPC mechanism to communicate the user's

+     security identifiers to the server.

+

+     For Windows, this means that the platform specific IPC messaging

+     allows a username and session identifier to be sent separate from

+     the username and session identifier that will be obtained via the

+     use of Local RPC. If the Local RPC authenticates the user as

+     "SYSTEM" and session 0, then the communicated values (if provided)

+     will be used instead.

+

+ + implement client side of IPC routine.

+

+   - [windows] the client side IPC routine is produced by compiling a

+     IDL file.  The IDL defines an interface with a single function:

+

+     __int32 ccapi_Message  (

+                 [in] handle_t h,

+                 [in, string]  unsigned char * client_name,

+                 [in] struct _LUID  luid,

+                 [in] __int32 in_len,

+                 [in, string, size_is(in_len)] unsigned char * in_buf,

+                 [in] __int32 out_size,

+                 [out] __int32 * out_len,

+                 [out, string, size_is(out_size)] unsigned char

+                     out_buf[*]);

+

+     The handle is a Local RPC specific handle used to identify the

+     request. The client_name and luid are the override values for the

+     username and session identifier for use during Windows login.  The

+     rest of the parameters provide the input and output buffers as well

+     as allow communication of the actual length of the message data

+     that is required by cci_msg_unflatten().

+

+ + if the CCAPI server is per-session, the shared client library is

+   responsible for ensuring that an instance of the server is running in

+   the current session.  If not, the library must initiate an instance

+   of the CCAPI server prior to performing any IPC requests.

+

+The platform dependent code is responsible for producing a server

+executable:

+

+ + The server executable is built from cc_server.lib and cc_common.lib

+   plus platform dependent glue.

+

+   - [windows] The Windows CCAPI Server is being built using the

+     per-system model.  The platform specific code is responsible for

+     providing NT Service Management routines for installation and

+     removal as well as the NT Service Entry Points used when the

+     process is started as an NT Service.

+

+     link cc_server.lib and cc_common.lib with platform dependent

+     routines to produce krbcc32s.exe.

+

+ + Based upon the platform requirements, the server may be constructed

+   to be per-session or per-system.   The selected IPC mechanism must

+   enforce the appropriate scoping.

+

+ + The platform dependent startup routines will perform platform

+   specific initialization including the IPC engine and call the

+   platform independent initialization routine ccs_serv_initialize()

+

+ + The platform dependent shutdown routines will perform platform

+   specific cleanup including the IPC engine and call the platform

+   independent function ccs_serv_cleanup() prior to process termination.

+

+ + For each inbound CCAPI request, the server will unmarshall the

+   request using cci_msg_unflatten() to produce a cc_msg_t object,

+   construct cc_auth_info_t and cc_session_info_t objects to represent

+   the platform dependent authentication and session data, call

+   ccs_serv_process_msg() to process the request, call cci_msg_flatten()

+   to marhall the response, transmit the response to the caller, and

+   then cleanup the request and response cc_msg_t objects with

+   cci_msg_destroy().

+

+ + The cc_auth_info_t and cc_session_info_t objects are structures

+   storing opaque binary (data, length) representations of the

+   authentication and session data.   These are stored as part of ccache

+   collection and ccaches.  ccs_serv_process_msg() will perform a binary

+   comparison of the stored data with the data provided in the current

+   request.   If they do not match, the request will be denied.  It is

+   necessary that the data generated data always be the same.   If

+   username strings are not case-sensitive, they should be normalized

+   before being passed to ccs_serv_process_msg().

+

+ + The current cc_server.lib routines assume that one request at a time

+   is being processed.  If the IPC engine allows for more than one

+   request to be simultaneously received in separate threads, then the

+   call to ccs_serv_process_msg() must be wrapped by a critical section.

+   Future enhancements to cc_server.lib will allow for per-object

+   mutexes.  When available the platform specific glue must provide

+   functions to create, obtain, release, and destroy mutex objects.

+

+