diff options
Diffstat (limited to 'lib/orber/doc/src/ch_interceptors.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_interceptors.xml | 278 |
1 files changed, 0 insertions, 278 deletions
diff --git a/lib/orber/doc/src/ch_interceptors.xml b/lib/orber/doc/src/ch_interceptors.xml deleted file mode 100644 index 4a9f8e69ca..0000000000 --- a/lib/orber/doc/src/ch_interceptors.xml +++ /dev/null @@ -1,278 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2001</year><year>2017</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Orber Interceptors</title> - <prepared>Nick</prepared> - <docno></docno> - <date>2001-08-16</date> - <rev></rev> - <file>ch_interceptors.xml</file> - </header> - - <section> - <title>Using Interceptors</title> - <p>For Inter-ORB communication, e.g., via <c>IIOP</c>, it is possible - to intercept requests and replies. To be able to use <c>Interceptors</c> - Orber the configuration parameter <c>interceptors</c> must be defined.</p> - - <section> - <title>Configure Orber to Use Interceptors</title> - <p>The configuration parameter <c>interceptors</c> must be defined, e.g., - as command line option:</p> - <code type="none"> -erl -orber interceptors "{native, ['myInterceptor']}" - </code> - <p>It is possible to use more than one interceptor; simply add them to the - list and they will be invoked in the same order as they appear in the list.</p> - <p>One can also active and deactivate an interceptor during - run-time, but this will only affect currently existing connections. - For more information, consult Orber's Reference Manual regarding the - operations <c>orber:activate_audit_trail/0/1</c> and - <c>orber:activate_audit_trail/0/1.</c></p> - </section> - - <section> - <title>Creating Interceptors</title> - <p>Each supplied interceptor <em>must</em> export the following functions:</p> - <list type="bulleted"> - <item><em>new_out_connection/3/5</em> - one of these operations is called when - a client application calls an object residing on remote ORB. - If an interceptor exports both versions, arity 3 and 5, which - operation that will be invoked is Orber internal.</item> - <item><em>new_in_connection/3/5</em> - one of these operations is invoked - when a client side ORB tries to set up a connection to the target ORB. - If an interceptor exports both versions, arity 3 and 5, which - operation that will be invoked is Orber internal.</item> - <item><em>out_request/6</em> - supplies all request data on the client side - ORB.</item> - <item><em>out_request_encoded/6</em> - similar to <c>out_request</c> - but the request body is encode.</item> - <item><em>in_request_encoded/6</em> - after a new request arrives at the - target ORB the request data is passed to the interceptor in - encoded format.</item> - <item><em>in_request/6</em> - prior to invoking the operation on the - target object, the interceptor <c>in_request</c> is called.</item> - <item><em>out_reply/6</em> - after the target object replied the - <c>out_reply</c> operation is called with the result of the object - invocation.</item> - <item><em>out_reply_encoded/6</em> - before sending a reply back to the - client side ORB this operation is called with the result in - encoded format.</item> - <item><em>in_reply_encoded/6</em> - after the client side ORB receives - a reply this function is called with the reply in encoded - format.</item> - <item><em>in_reply/6</em> - before delivering the reply to the client - this operation is invoked.</item> - <item><em>closed_in_connection/1</em> - when a connection is terminated - on the client side this function is called.</item> - <item><em>closed_out_connection/1</em> - if an outgoing connection is - terminated this operation will be invoked.</item> - </list> - <p>The operations <c>new_out_connection</c>, <c>new_in_connection</c>, - <c>closed_in_connection</c> and <c>closed_out_connection</c> operations - are only invoked <em>once</em> per connection. The remaining operations - are called, as shown below, for every Request/Reply to/from remote - CORBA Objects.</p> - <marker id="interceptor_operations"></marker> - <image file="interceptor_operations.gif"> - <icaption> -The Invocation Order of Interceptor Functions.</icaption> - </image> - </section> - </section> - - <section> - <title>Interceptor Example</title> - <p>Assume we want to create a simple access service which purpose is to:</p> - <list type="bulleted"> - <item>Only allow incoming request from ORB's residing on a certain set of - nodes.</item> - <item>Restrict the objects any client may invoke operations on.</item> - <item>Only allow outgoing requests to call a limited set of external - ORB's.</item> - <item>Add a checksum to each binary request/reply body.</item> - </list> - <p>To restricts the access we use a <c>protected</c> and <c>named</c> ets-table - holding all information. How the ets-table is initiated and maintained - is implementation specific, but it contain - <c>{Node, ObjectTable, ChecksumModule}</c> where <c>Node</c> is used as - ets-key, <c>ObjectTable</c> is a reference to another ets-table in which - we store which objects the clients are allowed to invoke operations on - and <c>ChecksumModule</c> determines which module we should use to handle - the checksums. </p> - <code type="erl"> -new_in_connection(Arg, Host, Port) -> - %% Since we only use one interceptor we do not care about the - %% input Arg since it is set do undefined by Orber. - case ets:lookup(in_access_table, Host) of - [] -> - %% We may want to log the Host/Port to see if someone tried - %% to hack in to our system. - exit("Access not granted"); - [{Host, ObjTable, ChecksumModule}] -> - {ObjTable, ChecksumModule} - end. - </code> - <p>The returned tuple, i.e., {ObjTable, ChecksumModule}, will be passed - as the first argument whenever invoking one of the interceptor functions. - Unless the connection attempt did not fail we are now ready for receiving - requests from the client side ORB.</p> - <p>When a new request comes in the first interceptor function to be invoked is - <c>in_request_encoded</c>. We will remove the checksum from the coded - request body in the following way:</p> - <code type="erl"> -in_request_encoded({ObjTable, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:remove_checksum(Bin), - {NewBin, Extra}. - </code> - <p>If the checksum check fails the <c>ChecksumModule</c> should invoke exit/1. - But if the check succeeded we are now ready to check if the client-ORB - objects are allowed to invoke operations on the target object. Please note, - it is possible to run both checks in <c>in_request_encoded</c>. Please - note, the checksum calculation must be relatively fast to ensure a - good throughput.</p> - <p>If we want to we can restrict any clients to only use a subset of operations - exported by a server:</p> - <code type="erl"> -in_request({ObjTable, ChecksumModule}, ObjKey, Ctx, Op, Params, Extra) -> - case ets:lookup(ObjTable, {ObjKey, Op}) of - [] -> - exit("Client tried to invoke illegal operation"); - [SomeData] -> - {Params, Extra} - end. - </code> - <p>At this point Orber are now ready to invoke the operation on the target - object. Since we do not care about what the reply is the <c>out_reply</c> - function do nothing, i.e.:</p> - <code type="erl"> -out_reply(_, _, _, _, Reply, Extra) -> - {Reply, Extra}. - </code> - <p>If the client side ORB expects a checksum to be added to the reply we - add it by using:</p> - <code type="erl"> -out_reply_encoded({ObjTable, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:add_checksum(Bin), - {NewBin, Extra}. - </code> - <warning> - <p>If we manipulate the binary as above the behavior <em>must</em> - be <c>Bin == remove_checksum(add_checksum(Bin))</c>.</p> - </warning> - <p>For outgoing requests the principle is the same. Hence, it is not further - described here. The complete interceptor module would look like:</p> - <code type="erl"> --module(myInterceptor). - -%% Interceptor functions. --export([new_out_connection/3, - new_in_connection/3, - closed_in_connection/1, - closed_out_connection/1, - in_request_encoded/6, - in_reply_encoded/6, - out_reply_encoded/6, - out_request_encoded/6, - in_request/6, - in_reply/6, - out_reply/6, - out_request/6]). - -new_in_connection(Arg, Host, Port) -> - %% Since we only use one interceptor we do not care about the - %% input Arg since it is set do undefined by Orber. - case ets:lookup(in_access_table, Host) of - [] -> - %% We may want to log the Host/Port to see if someone tried - %% to hack in to our system. - exit("Access not granted"); - [{Host, ObjTable, ChecksumModule}] -> - {ObjTable, ChecksumModule} - end. - -new_out_connection(Arg, Host, Port) -> - case ets:lookup(out_access_table, Host) of - [] -> - exit("Access not granted"); - [{Host, ObjTable, ChecksumModule}] -> - {ObjTable, ChecksumModule} - end. - -in_request_encoded({_, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:remove_checksum(Bin), - {NewBin, Extra}. - -in_request({ObjTable, _}, ObjKey, Ctx, Op, Params, Extra) -> - case ets:lookup(ObjTable, {ObjKey, Op}) of - [] -> - exit("Client tried to invoke illegal operation"); - [SomeData] -> - {Params, Extra} - end. - -out_reply(_, _, _, _, Reply, Extra) -> - {Reply, Extra}. - -out_reply_encoded({_, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:add_checksum(Bin), - {NewBin, Extra}. - -out_request({ObjTable, _}, ObjKey, Ctx, Op, Params, Extra) -> - case ets:lookup(ObjTable, {ObjKey, Op}) of - [] -> - exit("Client tried to invoke illegal operation"); - [SomeData] -> - {Params, Extra} - end. - -out_request_encoded({_, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:add_checksum(Bin), - {NewBin, Extra}. - -in_reply_encoded({_, ChecksumModule}, ObjKey, Ctx, Op, Bin, Extra) -> - NewBin = ChecksumModule:remove_checksum(Bin), - {NewBin, Extra}. - -in_reply(_, _, _, _, Reply, Extra) -> - {Reply, Extra}. - -closed_in_connection(Arg) -> - %% Nothing to clean up. - Arg. - -closed_out_connection(Arg) -> - %% Nothing to clean up. - Arg. - </code> - <note> - <p>One can also use interceptors for debugging purposes, e.g., - print which objects and operations are invoked with which arguments - and the outcome of the operation. In conjunction with the configuration - parameter <c>orber_debug_level</c> it is rather easy to find out what - went wrong or just to log the traffic. </p> - </note> - </section> -</chapter> - |