/* * Copyright (c) 2010 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of Apple Inc. ("Apple") nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * Portions of this software have been released under the following terms: * * (c) Copyright 1989-1993 OPEN SOFTWARE FOUNDATION, INC. * (c) Copyright 1989-1993 HEWLETT-PACKARD COMPANY * (c) Copyright 1989-1993 DIGITAL EQUIPMENT CORPORATION * * To anyone who acknowledges that this file is provided "AS IS" * without any express or implied warranty: * permission to use, copy, modify, and distribute this file for any * purpose is hereby granted without fee, provided that the above * copyright notices and this notice appears in all source code copies, * and that none of the names of Open Software Foundation, Inc., Hewlett- * Packard Company or Digital Equipment Corporation be used * in advertising or publicity pertaining to distribution of the software * without specific, written prior permission. Neither Open Software * Foundation, Inc., Hewlett-Packard Company nor Digital * Equipment Corporation makes any representations about the suitability * of this software for any purpose. * * Copyright (c) 2007, Novell, Inc. All rights reserved. * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of Novell Inc. nor the names of its contributors * may be used to endorse or promote products derived from this * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * @APPLE_LICENSE_HEADER_END@ */ /* ** ** NAME: ** ** conv.idl ** ** FACILITY: ** ** Remote Procedure Call (RPC) ** ** ABSTRACT: ** ** Conversation Manager (conv) Interface. ** ** This interface defines procedure that are architecturally defined ** by the NCA datagram-oriented RPC protocol. Calls to these procedures ** are made by servers to clients. I.e., an application client makes ** a call to an application server and (sometimes) the application server ** makes a call on one of these procedures back to the application client. ** (The application server is thus transiently a "client.) ** ** All application clients must be prepared to handle calls on this ** interface. (Note that these calls are typically transparently handled ** by the client's runtime environment and not be the application client ** itself.) ** ** Note well that calls made on this interface are not "real callbacks". ** (They're sometimes called "who-are-you [or WAY] callbacks".) Whereas ** the activity ID in the headers of packets that are parts of real ** callbacks matches (i.e., must match) the activity ID of the surrounding ** call, calls on this interface use a different activity ID. This ** is a requirement that arises from the fact that this interface is ** used in maintaining "at most once" call semantics (i.e., protection ** against duplication of datagrams) for calls to non-idempotent ** procedures. ** ** */ [uuid(333A2276-0000-0000-0D00-00809C000000), version(3)] interface conv { /* * C O N V _ W H O _ A R E _ Y O U * * This procedure is called by a server to a client when the server has * just received a non-idempotent call request from a client about whom * the server knows nothing. The server calls this procedure to determine * the current sequence number of the client (identified by its activity * ID) in question. If the returned sequence number is higher than the * one in the request that prompted the "who-are-you" call, the request * must be a duplicated and is ignored. * * This procedure is necessarily (marked) "idempotent" since it supports * (and hence can not depend on) non-idempotent call semantics. * * It is expected (though not logically required) that servers will * maintain a cache of (client activity ID, current sequence number) * pairs to minimize the number of times this procedure needs to be called * by servers. Cache entries can be dropped as is convenient to servers * since the cached information can always be re-obtained by making calls * on this procedure. * * The server passes its boot time back to the client to protect against * the case where the server receives a request, executes it, crashes * before sending the reply, and then reboots and receives a duplicate * of the request. In this scenario, the rebooted server will necessarily * make a "who-are-you" call. However, the input boot time will be * different and the client (processing the "who-are-you" call), which * will have saved the server's boot time from the "who-are-you" call * made by the previous incarnation of the server, will notice this and * return a non-zero error status to the server, prompting the server * to not execute the original request. (Note that the client will still * not know whether the call was executed zero or one times, but all * we're promising is that it isn't executed more than once.) */ [idempotent] void conv_who_are_you( [in] handle_t h, [in] idl_uuid_t *actuid, [in] unsigned32 boot_time, [out] unsigned32 *seq, [out] unsigned32 *st ); /* * C O N V _ W H O _ A R E _ Y O U 2 * * This is a newer version of "conv_who_are_you" and has a superset of * the older call's semantics. The additional semantics are that this * call returns a UUID that uniquely identifies the client's address * space (CAS UUID). The CAS UUID is used in cases where the server * is monitoring the "liveness" of a client which is not currently making * a remote call to the server (e.g., in case the server application * is holding state on behalf of the client and it wants to discard or * otherwise clean up this state if the client crashes). * * For compatibility with old clients, servers do not (should not) call * this procedure to get client sequence number information. Rather, * they call this procedure if, in the course of processing a client's * call, they need the CAS UUID. This procedure is constructed as a * superset of the old "who-are-you" to make it possible that some day * (or in environments with no old clients), servers WILL call this * procedure to get the client's sequence number (and hence avoid making * an EXTRA call to get the CAS UUID). */ [idempotent] void conv_who_are_you2( [in] handle_t h, [in] idl_uuid_t *actuid, [in] unsigned32 boot_time, [out] unsigned32 *seq, [out] idl_uuid_t *cas_uuid, [out] unsigned32 *st ); /* * C O N V _ A R E _ Y O U _ T H E R E * * This interface is used for server to client "liveness" checking. * If a server is in the process of receiving input from a client and * has not received any data for a period of time defined by the liveness * timeout, the server may attempt to do an "are_you_there" callback. This * callback is usually the servers last resort before declaring an RPC * dead. */ [idempotent] void conv_are_you_there( [in] handle_t h, [in] idl_uuid_t *actuid, [in] unsigned32 boot_time, [out] unsigned32 *st ); /* * C O N V _ W H O _ A R E _ Y O U _ A U T H * * Version of "conv_who_are_you" (actually, "conv_who_are_you2") that's * used to do authenticated RPC. Instead of calling "conv_who_are_you" * the server (callback-er) can use this function and supply (in addition * to the regular inputs) an "authentication challenge" to the client * (the callback-ee) and receive as output (in addition to the regular * outputs) a "response" to the challenge. * * The challenge is plaintext containing a nonce (random value) and the * response is an "authenticator". An authenticator consists of (1) a * "ticket", and (2) the nonce sealed under the "session key". The * ticket is encrypted in the servers key and contains (1) the identity * of the client, and (2) the session key. (See the MIT Project Athena * Kerberos papers for an example of how a particular realization of * the authenticator abstraction.) */ [idempotent] void conv_who_are_you_auth( [in] handle_t h, [in] idl_uuid_t *actuid, [in] unsigned32 boot_time, [in, size_is(in_len)] byte in_data[], [in] signed32 in_len, [in] signed32 out_max_len, [out] unsigned32 *seq, [out] idl_uuid_t *cas_uuid, [out, length_is(*out_len), size_is(out_max_len)] byte out_data[], [out] signed32 *out_len, [out] unsigned32 *st ); /* * C O N V _ W H O _ A R E _ Y O U _ A U T H _ M O R E * * This routine is used, in conjunction with the conv_who_are_you_auth() * operation, for retrieving oversized PACs. In the event that a client's * credentials are too large to fit within a single DG packet, the server * can retrieve the PAC, packet by packet, by repeated calls on this * operation. * * Note that because the "conv" interface is serviced directly by the * the DG protocol (as opposed to being handled by a call executor thread), * there is no additional client overhead with retrieving the PAC by * multiple single-packet calls, rather than a single multiple-packet call. * The small amount of overhead induced on the server side is more than * compensated for by being able to avoid adding flow-control/windowing * to the DG protocol's internal handling of the conv interface. * * Logically, this call returns * * client_credentials[index ... (index+out_max_len-1)] */ [idempotent] void conv_who_are_you_auth_more( [in] handle_t h, [in] idl_uuid_t *actuid, [in] unsigned32 boot_time, [in] signed32 index, [in] signed32 out_max_len, [out, length_is(*out_len), size_is(out_max_len)] byte out_data[], [out] signed32 *out_len, [out] unsigned32 *st ); }