Proposed RPC design for Windows CCAPI clients and server

The proposal is for a single user; the solution is replicated for each user logged onto the PC.

Conventions & clarifications

"Client" and "server" refer to the CCAPI client and server.

The CCAPI client acts as both an RPC client and RPC server and the CCAPI server acts as both an RPC client and RPC server.

• The RPC call from the CCAPI client to the CCAPI server is called the "request." In this mode, the CCAPI client is the RPC client and the CCAPI server is the RPC server.
• The RPC call from the CCAPI server to the CCAPI client is called the "reply." In this mode, the CCAPI client is the RPC server and the CCAPI server is the RPC client.

The Windows username is referred to below as "<USER>."

The Windows Logon Security Identifier is referred to as "<LSID>."

<UUID> means a thread-specific UUID.

<SST> means server start time, a time_t.

A description of client and server authentication has not been added yet.

Design Requirements

• The server's OS-independent code is single threaded, because it must operate on platforms that do not allow multiple threads.
• The client and server must be able to maintain connections, where state is maintained between individual messages.
• Individual messages must be handled in a single threaded server.
• The server must be able to detect when a client dies, so that any connection state can be cleaned up.

Design

The server and each client create an RPC endpoint. The server's endpoint is CCS_<LSID> and the client's endpoint is CCAPI_<UUID>, where each client geta a UUID.

On Windows, the server's ccs_pipe_t type is a char* and is set to the client UUID.

How is the request handled in the server and the reply sent to the client?

One straightforward way is for the reply to be the returned data in the request RPC call (an [out] parameter). That is, data passed from the RPC server to the RPC client. The request handler calls ccs_server_handle_request. Eventually, the server code calls ccs_os_server_send_reply, which saves the reply somewhere. When the server eventually returns to the request handler, the handler returns the saved reply to the client.

But this doesn't work. If two clients A and B ask for the same lock, A will acquire the lock and B will have to wait. But if the single threaded server waits for B's lock, it will never handle A's unlock message. Therefore the server must return to B's request handler and not send a reply to B. So this method will not work.

Instead, there are listener and worker threads in Windows-specific code.

The client's cci_os_ipc function waits for ccs_reply. The client sends the request, including it's UUID, from which the server can construct the endpoint on which to call ccs_reply.

The server's listener thread listens for RPC requests. The request handler puts each request/reply endpoint in a queue and returns to the client.

The server's worker thread removes items from the queue, calls ccs_server_handle_request. ccs_server_handle_request takes both the request data and the client UUID . Eventually ccs_os_server_send_reply is called, with the reply data and client UUID in the reply_pipe. ccs_os_server_send_reply calls ccs_reply on the client's endpoint, which sends the reply to the client.

Is there any security issue with the client listening for RPC calls from the server?

Connections

If the client wants state to be maintained on the server, the client creates a connection. When the connection is closed, the server cleans up any state associated with the connection.

Any given thread in an application process could want to create a connection. When cci_ipc_thread_init is called, the connection thread-local variables are initialized. New connections are created when cci_os_ipc() (via _cci_ipc_send) is called and no connection was previously established. Basically we lazily establish connections so the client doesn't talk to the server until it has to.

Detecting client exit

The server must be able to detect when clients disappear, so the server can free any resources that had been held for the client.

The Windows RPC API does not appear to provide a notification for an endpoint disappearing. It does provide a way to ask if an endpoint is listening. This is useful for polling, but we want a better performing solution than that.

The client has an isAlive function on its endpoint.

To detect the client disappearing without using polling, the server makes an asynchronous call to the isAlive function on the client's endpoint. The isAlive function never returns. When the client exits for any reason, it's endpoint will be closed and the server's function call will return an error. The asynchronous call on the server means no additional threads are used.

Windows provides a number of notification methods to signal I/O completion. Among them are I/O completion ports and callback functions. I chose callback functions because they appear to consume fewer resources.

RPC Endpoint / Function summary

• The server creates one CCS_<LSID> endpoint to listen for connection requests and client requests. It has the functions
  • ccs_rpc_connect(msgtype, UUIDlen, <UUID>, status)
  • ccs_rpc_request(msgtype, UUIDlen, <UUID>, msglen, msg, SST, status) called by client. NB: The windows server sets the in_client_pipe to the in_reply_pipe.
    
• Each client thread creates a CCAPI_<UUID> endpoint. It has the functions
  • isAlive [function never returns.]
  • ccs_rpc_request_reply(msgtype, SST, replylen, reply, status)
  • ccs_rpc_connect_reply(msgtype, SST, status

Windows-specific implementation details

Client CCAPI library initialization:

This code runs when the CCAPI DLL is loaded.

• ?

Client initialization:

This code runs when cci_os_ipc_thread_init is called:

• Generate <UUID> and save in thread-specific storage. This serves as the client ID / ccs_pipe_t.
• Create client endpoint.
• Listen on client endpoint.
• Create canonical server connection endpoint from the <LSID>, which the client and server should have in common.
• Test if server is listening to the CCS_<LSID> endpoint.
  • If not, quit. (! Start it?)
• Call ccs_connect(<UUID>) on the CCS_<LSID> endpoint.
• Save SST in thread-specific storage.

Server initialization:

[old]

• Server is initialized by client starting a new process. There should be only one server process per Windows username.

[new]

• Server is started by kfwlogon (as is done currently).
• Capture server start time (SST).
• Start listener thread, create listener endpoint, listen on CCS_<LSID> endpoint.

Establishing a connection:

• Client calls ccs_connect(<UUID>) on server's CCS_<LSID> endpoint.
• Client gets back and stores SST in thread-specific storage.
• If new connection, server ...
  • adds connection to connection table
  • calls isAlive on CCAPI_<UUID>.
    • NB: isAlive never returns.

Client request:

The server's reply to the client's request is not synchronous.

• Client calls ccs_rpc_request(msglen, msg, msgtype, UUIDlen, <UUID>, SST, status) on server's endpoint.
• Server listen thread receives message, queues request.
• Server worker thread dequeues request, processes, calls ccs_rpc_reply(replylen, reply, msgtype, status) on CCAPI_<UUID>.
• Server checks SST. If server's SST is different, it means server has restarted since client created connection.
• Client receives reply.

Detecting client exit

• When connection created, client created an endpoint.
• Server calls isAlive on client's endpoint.
• When isAlive returns, the server's notification callback will be called. Call back routine queues a DISCONNECT pseudo-message. When the server's worker thread handles the DISCONNECT, it will release connection resources.

Detecting server exit

• Client's call to ccs_rpc_request will return an error if the server has gone away.

------
Stop:
Start:

/* 
   Unix SMB/CIFS implementation.
   struct samu access routines
   Copyright (C) Jeremy Allison 		1996-2001
   Copyright (C) Luke Kenneth Casson Leighton 	1996-1998
   Copyright (C) Gerald (Jerry) Carter		2000-2006
   Copyright (C) Andrew Bartlett		2001-2002
   Copyright (C) Stefan (metze) Metzmacher	2002

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#include "includes.h"
#include "../libcli/auth/libcli_auth.h"
#include "../libcli/security/security.h"

#undef DBGC_CLASS
#define DBGC_CLASS DBGC_PASSDB

/**
 * @todo Redefine this to NULL, but this changes the API because
 *       much of samba assumes that the pdb_get...() funtions 
 *       return strings.  (ie not null-pointers).
 *       See also pdb_fill_default_sam().
 */

#define PDB_NOT_QUITE_NULL ""

/*********************************************************************
 Collection of get...() functions for struct samu.
 ********************************************************************/

uint32_t pdb_get_acct_ctrl(const struct samu *sampass)
{
	return sampass->acct_ctrl;
}

time_t pdb_get_logon_time(const struct samu *sampass)
{
	return sampass->logon_time;
}

time_t pdb_get_logoff_time(const struct samu *sampass)
{
	return sampass->logoff_time;
}

time_t pdb_get_kickoff_time(const struct samu *sampass)
{
	return sampass->kickoff_time;
}

time_t pdb_get_bad_password_time(const struct samu *sampass)
{
	return sampass->bad_password_time;
}

time_t pdb_get_pass_last_set_time(const struct samu *sampass)
{
	return sampass->pass_last_set_time;
}

time_t pdb_get_pass_can_change_time(const struct samu *sampass)
{
	uint32_t allow;

	/* if the last set time is zero, it means the user cannot 
	   change their password, and this time must be zero.   jmcd 
	*/
	if (sampass->pass_last_set_time == 0)
		return (time_t) 0;

	/* if the time is max, and the field has been changed,
	   we're trying to update this real value from the sampass
	   to indicate that the user cannot change their password.  jmcd
	*/
	if (sampass->pass_can_change_time == get_time_t_max() &&
	    IS_SAM_CHANGED(sampass, PDB_CANCHANGETIME))
		return sampass->pass_can_change_time;

	if (!pdb_get_account_policy(PDB_POLICY_MIN_PASSWORD_AGE, &allow))
		allow = 0;

	/* in normal cases, just calculate it from policy */
	return sampass->pass_last_set_time + allow;
}

/* we need this for loading from the backend, so that we don't overwrite
   non-changed max times, otherwise the pass_can_change checking won't work */
time_t pdb_get_pass_can_change_time_noncalc(const struct samu *sampass)
{
	return sampass->pass_can_change_time;
}

time_t pdb_get_pass_must_change_time(const struct samu *sampass)
{
	uint32_t expire;

	if (sampass->pass_last_set_time == 0)
		return (time_t) 0;

	if (sampass->acct_ctrl & ACB_PWNOEXP)
		return get_time_t_max();

	if (!pdb_get_account_policy(PDB_POLICY_MAX_PASSWORD_AGE, &expire)
	    || expire == (uint32_t)-1 || expire == 0)
		return get_time_t_max();

	return sampass->pass_last_set_time + expire;
}

bool pdb_get_pass_can_change(const struct samu *sampass)
{
	if (sampass->pass_can_change_time == get_time_t_max() &&
	    sampass->pass_last_set_time != 0)
		return False;
	return True;
}

uint16_t pdb_get_logon_divs(const struct samu *sampass)
{
	return sampass->logon_divs;
}

uint32_t pdb_get_hours_len(const struct samu *sampass)
{
	return sampass->hours_len;
}

const uint8 *pdb_get_hours(const struct samu *sampass)
{
	return (sampass->hours);
}

const uint8 *pdb_get_nt_passwd(const struct samu *sampass)
{
	SMB_ASSERT((!sampass->nt_pw.data) 
		   || sampass->nt_pw.length == NT_HASH_LEN);
	return (uint8 *)sampass->nt_pw.data;
}

const uint8 *pdb_get_lanman_passwd(const struct samu *sampass)
{
	SMB_ASSERT((!sampass->lm_pw.data) 
		   || sampass->lm_pw.length == LM_HASH_LEN);
	return (uint8 *)sampass->lm_pw.data;
}

const uint8 *pdb_get_pw_history(const struct samu *sampass, uint32_t *current_hist_len)
{
	SMB_ASSERT((!sampass->nt_pw_his.data) 
	   || ((sampass->nt_pw_his.length % PW_HISTORY_ENTRY_LEN) == 0));
	*current_hist_len = sampass->nt_pw_his.length / PW_HISTORY_ENTRY_LEN;
	return (uint8 *)sampass->nt_pw_his.data;
}

/* Return the plaintext password if known.  Most of the time
   it isn't, so don't assume anything magic about this function.

   Used to pass the plaintext to passdb backends that might 
   want to store more than just the NTLM hashes.
*/
const char *pdb_get_plaintext_passwd(const struct samu *sampass)
{
	return sampass->plaintext_pw;
}

const struct dom_sid *pdb_get_user_sid(const struct samu *sampass)
{
	return &sampass->user_sid;
}

const struct dom_sid *pdb_get_group_sid(struct samu *sampass)
{
	NTSTATUS status;

	/* Return the cached group SID if we have that */
	if (sampass->group_sid) {
		return sampass->group_sid;
	}

	/* No algorithmic mapping, meaning that we have to figure out the
	   primary group SID according to group mapping and the user SID must
	   be a newly allocated one.  We rely on the user's Unix primary gid.
	   We have no choice but to fail if we can't find it. */
	status = get_primary_group_sid(sampass,
					pdb_get_username(sampass),
					&sampass->unix_pw,
					&sampass->group_sid);
	if (!NT_STATUS_IS_OK(status)) {
		return NULL;
	}

	return sampass->group_sid;
}

/**
 * Get flags showing what is initalised in the struct samu
 * @param sampass the struct samu in question
 * @return the flags indicating the members initialised in the struct.
 **/

enum pdb_value_state pdb_get_init_flags(const struct samu *sampass, enum pdb_elements element)
{
	enum pdb_value_state ret = PDB_DEFAULT;

        if (!sampass->change_flags || !sampass->set_flags)
        	return ret;

        if (bitmap_query(sampass->set_flags, element)) {
		DEBUG(11, ("element %d: SET\n", element)); 
        	ret = PDB_SET;
	}

        if (bitmap_query(sampass->change_flags, element)) {
		DEBUG(11, ("element %d: CHANGED\n", element)); 
        	ret = PDB_CHANGED;
	}

	if (ret == PDB_DEFAULT) {
		DEBUG(11, ("element %d: DEFAULT\n", element)); 
	}

        return ret;
}

const char *pdb_get_username(const struct samu *sampass)
{
	return sampass->username;
}

const char *pdb_get_domain(const struct samu *sampass)
{
	return sampass->domain;
}

const char *pdb_get_nt_username(const struct samu *sampass)
{
	return sampass->nt_username;
}

const char *pdb_get_fullname(const struct samu *sampass)
{
	return sampass->full_name;
}

const char *pdb_get_homedir(const struct samu *sampass)
{
	return sampass->home_dir;
}

const char *pdb_get_dir_drive(const struct samu *sampass)
{
	return sampass->dir_drive;
}

const char *pdb_get_logon_script(const struct samu *sampass)
{
	return sampass->logon_script;
}

const char *pdb_get_profile_path(const struct samu *sampass)
{
	return sampass->profile_path;
}

const char *pdb_get_acct_desc(const struct samu *sampass)
{
	return sampass->acct_desc;
}

const char *pdb_get_workstations(const struct samu *sampass)
{
	return sampass->workstations;
}

const char *pdb_get_comment(const struct samu *sampass)
{
	return sampass->comment;
}

const char *pdb_get_munged_dial(const struct samu *sampass)
{
	return sampass->munged_dial;
}

uint16_t pdb_get_bad_password_count(const struct samu *sampass)
{
	return sampass->bad_password_count;
}

uint16_t pdb_get_logon_count(const struct samu *sampass)
{
	return sampass->logon_count;
}

uint32_t pdb_get_unknown_6(const struct samu *sampass)
{
	return sampass->unknown_6;
}

void *pdb_get_backend_private_data(const struct samu *sampass, const struct pdb_methods *my_methods)
{
	if (my_methods == sampass->backend_private_methods) {
		return sampass->backend_private_data;
	} else {
		return NULL;
	}
}

/*********************************************************************
 Collection of set...() functions for struct samu.
 ********************************************************************/

bool pdb_set_acct_ctrl(struct samu *sampass, uint32_t acct_ctrl, enum pdb_value_state flag)
{
	sampass->acct_ctrl = acct_ctrl;
	return pdb_set_init_flags(sampass, PDB_ACCTCTRL, flag);
}

bool pdb_set_logon_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->logon_time = mytime;
	return pdb_set_init_flags(sampass, PDB_LOGONTIME, flag);
}

bool pdb_set_logoff_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->logoff_time = mytime;
	return pdb_set_init_flags(sampass, PDB_LOGOFFTIME, flag);
}

bool pdb_set_kickoff_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->kickoff_time = mytime;
	return pdb_set_init_flags(sampass, PDB_KICKOFFTIME, flag);
}

bool pdb_set_bad_password_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->bad_password_time = mytime;
	return pdb_set_init_flags(sampass, PDB_BAD_PASSWORD_TIME, flag);
}

bool pdb_set_pass_can_change_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->pass_can_change_time = mytime;
	return pdb_set_init_flags(sampass, PDB_CANCHANGETIME, flag);
}

bool pdb_set_pass_must_change_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->pass_must_change_time = mytime;
	return pdb_set_init_flags(sampass, PDB_MUSTCHANGETIME, flag);
}

bool pdb_set_pass_last_set_time(struct samu *sampass, time_t mytime, enum pdb_value_state flag)
{
	sampass->pass_last_set_time = mytime;
	return pdb_set_init_flags(sampass, PDB_PASSLASTSET, flag);
}

bool pdb_set_hours_len(struct samu *sampass, uint32_t len, enum pdb_value_state flag)
{
	sampass->hours_len = len;
	return pdb_set_init_flags(sampass, PDB_HOURSLEN, flag);
}

bool pdb_set_logon_divs(struct samu *sampass, uint16_t hours, enum pdb_value_state flag)
{
	sampass->logon_divs = hours;
	return pdb_set_init_flags(sampass, PDB_LOGONDIVS, flag);
}

/**
 * Set flags showing what is initalised in the struct samu
 * @param sampass the struct samu in question
 * @param flag The *new* flag to be set.  Old flags preserved
 *             this flag is only added.  
 **/

bool pdb_set_init_flags(struct samu *sampass, enum pdb_elements element, enum pdb_value_state value_flag)
{
        if (!sampass->set_flags) {
        	if ((sampass->set_flags = 
        		bitmap_talloc(sampass, 
        				PDB_COUNT))==NULL) {
        		DEBUG(0,("bitmap_talloc failed\n"));
        		return False;
        	}
        }
        if (!sampass->change_flags) {
        	if ((sampass->change_flags = 
        		bitmap_talloc(sampass, 
        				PDB_COUNT))==NULL) {
        		DEBUG(0,("bitmap_talloc failed\n"));
        		return False;
        	}
        }

        switch(value_flag) {
        	case PDB_CHANGED:
        		if (!bitmap_set(sampass->change_flags, element)) {
				DEBUG(0,("Can't set flag: %d in change_flags.\n",element));
				return False;
			}
        		if (!bitmap_set(sampass->set_flags, element)) {
				DEBUG(0,("Can't set flag: %d in set_flags.\n",element));
				return False;
			}
			DEBUG(11, ("element %d -> now CHANGED\n", element)); 
        		break;
        	case PDB_SET:
        		if (!bitmap_clear(sampass->change_flags, element)) {
				DEBUG(0,("Can't set flag: %d in change_flags.\n",element));
				return False;
			}
        		if (!bitmap_set(sampass->set_flags, element)) {
				DEBUG(0,("Can't set flag: %d in set_flags.\n",element));
				return False;
			}
			DEBUG(11, ("element %d -> now SET\n", element)); 
        		break;
        	case PDB_DEFAULT:
        	default:
        		if (!bitmap_clear(sampass->change_flags, element)) {
				DEBUG(0,("Can't set flag: %d in change_flags.\n",element));
				return False;
			}
        		if (!bitmap_clear(sampass->set_flags, element)) {
				DEBUG(0,("Can't set flag: %d in set_flags.\n",element));
				return False;
			}
			DEBUG(11, ("element %d -> now DEFAULT\n", element)); 
        		break;
	}

        return True;
}

bool pdb_set_user_sid(struct samu *sampass, const struct dom_sid *u_sid, enum pdb_value_state flag)
{
	if (!u_sid)
		return False;

	sid_copy(&sampass->user_sid, u_sid);

	DEBUG(10, ("pdb_set_user_sid: setting user sid %s\n", 
		    sid_string_dbg(&sampass->user_sid)));

	return pdb_set_init_flags(sampass, PDB_USERSID, flag);
}

bool pdb_set_user_sid_from_string(struct samu *sampass, fstring u_sid, enum pdb_value_state flag)
{
	struct dom_sid new_sid;

	if (!u_sid)
		return False;

	DEBUG(10, ("pdb_set_user_sid_from_string: setting user sid %s\n",
		   u_sid));

	if (!string_to_sid(&new_sid, u_sid)) { 
		DEBUG(1, ("pdb_set_user_sid_from_string: %s isn't a valid SID!\n", u_sid));
		return False;
	}

	if (!pdb_set_user_sid(sampass, &new_sid, flag)) {
		DEBUG(1, ("pdb_set_user_sid_from_string: could not set sid %s on struct samu!\n", u_sid));
		return False;
	}

	return True;
}

/********************************************************************
 We never fill this in from a passdb backend but rather set is