gkserver.h

Go to the documentation of this file.

/*
 * gkserver.h
 *
 * H225 Registration Admission and Security protocol handler
 *
 * Open H323 Library
 *
 * Copyright (c) 1998-2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.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.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * This code was based on original code from OpenGate of Egoboo Ltd. thanks
 * to Ashley Unitt for his efforts.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: gkserver.h,v $
 * Revision 2.14  2006/01/02 15:51:44  dsandras
 * Merged changes from OpenH323 Atlas_devel_2.
 *
 * Revision 2.13  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.12  2004/06/04 06:54:02  csoutheren
 * Migrated updates from OpenH323 1.14.1
 *
 * Revision 2.11  2004/04/25 02:53:29  rjongbloed
 * Fixed GNU 3.4 warnings
 *
 * Revision 2.10  2004/02/19 10:46:43  rjongbloed
 * Merged OpenH323 version 1.13.1 changes.
 *
 * Revision 2.9  2003/01/07 04:39:52  robertj
 * Updated to OpenH323 v1.11.2
 *
 * Revision 2.8  2002/11/10 11:33:16  robertj
 * Updated to OpenH323 v1.10.3
 *
 * Revision 2.7  2002/09/16 02:52:33  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 2.6  2002/09/04 06:01:46  robertj
 * Updated to OpenH323 v1.9.6
 *
 * Revision 2.5  2002/07/01 04:56:29  robertj
 * Updated to OpenH323 v1.9.1
 *
 * Revision 2.4  2002/03/22 06:57:48  robertj
 * Updated to OpenH323 version 1.8.2
 *
 * Revision 2.3  2002/02/11 09:32:11  robertj
 * Updated to openH323 v1.8.0
 *
 * Revision 2.2  2002/01/14 06:35:56  robertj
 * Updated to OpenH323 v1.7.9
 *
 * Revision 2.1  2001/08/13 05:10:39  robertj
 * Updates from OpenH323 v1.6.0 release.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 * Revision 1.74  2004/02/15 03:36:30  rjongbloed
 * Fixed bug in removing prefixes, plus added ability to have multiple endpoints
 *   with the same profix, thanks Rossano Ravelli
 *
 * Revision 1.73  2004/02/07 11:43:59  rjongbloed
 * Fixed deadlocks caused under high load by failure to check locking
 *   success. Also added functions to find destination endpoint.
 *   Thanks Federico Pinna and the gang at Reitek S.p.A.
 *
 * Revision 1.72  2003/12/24 07:08:47  csoutheren
 * Added TranslateAliasAddress on H323GatekeeperCall
 *
 * Revision 1.71  2003/12/11 05:39:04  csoutheren
 * Added storage of H.225 version in endpoint structure
 * Disabled sending RIPs to endpoints that cannot handle them
 *
 * Revision 1.70  2003/12/11 02:18:17  csoutheren
 * More fixes for NM deregistration problems. Seems to be fixed now :)
 *
 * Revision 1.69  2003/12/09 00:58:46  csoutheren
 * Fixed problem with endpoints deregistering
 *
 * Revision 1.68  2003/12/09 00:33:17  csoutheren
 * Added patch to prevent crash when NM unregisters from GK
 * Abject apologies to Rossano Ravelli for taking so long to add this
 *
 * Revision 1.67  2003/04/30 00:28:50  robertj
 * Redesigned the alternate credentials in ARQ system as old implementation
 *   was fraught with concurrency issues, most importantly it can cause false
 *   detection of replay attacks taking out an endpoint completely.
 *
 * Revision 1.66  2003/04/02 06:58:10  robertj
 * Added support for (optional) duplicate aliases in gatekeeper server, necessitating
 *   the removal of AddAlias and RemoveAlias functions.
 *
 * Revision 1.65  2003/04/02 06:07:12  robertj
 * Added H.323 Annex G Peer Element support to gatekeeper server.
 *
 * Revision 1.64  2003/04/01 07:30:52  robertj
 * Added function to translate alias into alias list and transport to make
 *   use of full information returned by peer element.
 *
 * Revision 1.63  2003/04/01 04:47:48  robertj
 * Abstracted H.225 RAS transaction processing (RIP and secondary thread) in
 *   server environment for use by H.501 peer elements.
 *
 * Revision 1.62  2003/03/26 07:10:03  robertj
 * Added more access functions.
 *
 * Revision 1.61  2003/03/17 22:52:06  craigs
 * Improvided useability of AddAlias and RemoveAlias
 *
 * Revision 1.60  2003/03/04 05:34:13  robertj
 * Fixed GNU warnings
 *
 * Revision 1.59  2003/03/04 05:27:51  robertj
 * Added statistics for rejected registrations and call admissions.
 *
 * Revision 1.58  2003/03/03 06:59:26  robertj
 * Fixed call SetBandwidth function so adjusts global bandwidth as well.
 *
 * Revision 1.57  2003/02/21 07:21:40  robertj
 * Fixed incorrect ancestor in PCLASSINFO()
 *
 * Revision 1.56  2003/02/21 05:28:39  craigs
 * Factored out code for user with peer elements
 *
 * Revision 1.55  2003/02/06 04:43:14  robertj
 * Changes to help with endpoints behind NAT.
 *
 * Revision 1.54  2003/02/03 03:58:06  robertj
 * Fixed use of local password database with ep's that have multiple aliases.
 *
 * Revision 1.53  2003/02/01 13:31:14  robertj
 * Changes to support CAT authentication in RAS.
 *
 * Revision 1.52  2002/12/17 01:25:23  robertj
 * Added call backs on gk server when ep indicates alerting or connect.
 *
 * Revision 1.51  2002/11/28 05:45:46  robertj
 * Fixed bug so can set total bandwidth while calls are in progress.
 *
 * Revision 1.50  2002/11/28 04:41:44  robertj
 * Added support for RAS ServiceControlIndication command.
 *
 * Revision 1.49  2002/11/27 06:54:52  robertj
 * Added Service Control Session management as per Annex K/H.323 via RAS
 *   only at this stage.
 * Added H.248 ASN and very primitive infrastructure for linking into the
 *   Service Control Session management system.
 * Added basic infrastructure for Annex K/H.323 HTTP transport system.
 * Added Call Credit Service Control to display account balances.
 *
 * Revision 1.48  2002/11/22 00:11:29  robertj
 * Added call start time.
 *
 * Revision 1.47  2002/11/18 23:40:45  robertj
 * Changed to use the H323EndPoint::CreateAuthenticators() function, we
 *   should use only one.
 *
 * Revision 1.46  2002/11/12 11:36:03  robertj
 * Added function to find endpoint by partial alias.
 * Optimised endpoint "indexes" to use sorted lists instead of dictionaries.
 *
 * Revision 1.45  2002/11/06 23:23:48  robertj
 * Fixed minor error in parameter, should be reference not value
 *
 * Revision 1.44  2002/10/29 00:12:02  robertj
 * Changed template classes so things like PSafeList actually creates the
 *   base collection class as well.
 * Improved setting of usage info, included getting it from BRQ etc.
 *
 * Revision 1.43  2002/10/21 00:54:47  robertj
 * Added function to unregister an endpoint via user interface.
 * Added reason code to call disengage.
 * Added ability to find call by a description string.
 *
 * Revision 1.42  2002/10/17 05:26:33  robertj
 * Added function to get at registered endpoints protocol version.
 *
 * Revision 1.41  2002/10/16 07:22:50  robertj
 * Added support for endpoints that do not support RRQ timeToLive parameter,
 *   will actively go see if ep is there using IRQ before expiring the ep.
 *
 * Revision 1.40  2002/10/01 08:17:34  robertj
 * Fixed (benign) race condition between client and server both wanting to do
 *   a DRQ of a call at the same time. Caused an Assert, but no crash.
 *
 * Revision 1.39  2002/09/26 01:27:31  robertj
 * Changed appliation info name in registered endpoint to be caseless string.
 *
 * Revision 1.38  2002/09/24 08:03:51  robertj
 * Added H.225 RAS protocol version number to registered endpoint structure.
 *
 * Revision 1.37  2002/09/19 09:15:56  robertj
 * Fixed problem with making (and assuring with multi-threading) IRQ and DRQ
 *   requests are sent to the correct endpoint address, thanks Martijn Roest.
 *
 * Revision 1.36  2002/09/16 01:14:15  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.35  2002/09/03 06:19:36  robertj
 * Normalised the multi-include header prevention ifdef/define symbol.
 *
 * Revision 1.34  2002/08/29 07:57:08  robertj
 * Added some statistics to gatekeeper server.
 *
 * Revision 1.33  2002/08/29 06:54:52  robertj
 * Removed redundent thread member variable from request info.
 *
 * Revision 1.32  2002/08/12 08:12:45  robertj
 * Added extra hint to help with ARQ using separate credentials from RRQ.
 *
 * Revision 1.31  2002/08/12 05:38:20  robertj
 * Changes to the RAS subsystem to support ability to make requests to client
 *   from gkserver without causing bottlenecks and race conditions.
 *
 * Revision 1.30  2002/08/05 10:03:47  robertj
 * Cosmetic changes to normalise the usage of pragma interface/implementation.
 *
 * Revision 1.29  2002/08/05 05:17:37  robertj
 * Fairly major modifications to support different authentication credentials
 *   in ARQ to the logged in ones on RRQ. For both client and server.
 * Various other H.235 authentication bugs and anomalies fixed on the way.
 *
 * Revision 1.28  2002/07/16 13:49:22  robertj
 * Added missing lock when removing call from endpoint.
 *
 * Revision 1.27  2002/07/11 09:33:56  robertj
 * Added access functions to various call statistics member variables.
 *
 * Revision 1.26  2002/07/11 07:01:37  robertj
 * Added Disengage() function to force call drop from gk server.
 * Added InfoRequest() function to force client to send an IRR.
 * Added ability to automatically clear calls if do not get IRR for it.
 *
 * Revision 1.25  2002/06/21 02:52:44  robertj
 * Fixed problem with double checking H.235 hashing, this causes failure as
 *   the authenticator thinks it is a replay attack.
 *
 * Revision 1.24  2002/06/19 05:03:08  robertj
 * Changed gk code to allow for H.235 security on an endpoint by endpoint basis.
 *
 * Revision 1.23  2002/06/12 03:55:21  robertj
 * Added function to add/remove multiple listeners in one go comparing against
 *   what is already running so does not interrupt unchanged listeners.
 *
 * Revision 1.22  2002/05/29 00:03:15  robertj
 * Fixed unsolicited IRR support in gk client and server,
 *   including support for IACK and INAK.
 *
 * Revision 1.21  2002/05/21 06:30:31  robertj
 * Changed GRQ to the same as all the other xRQ request handlers.
 *
 * Revision 1.20  2002/05/17 03:42:08  robertj
 * Fixed problems with H.235 authentication on RAS for server and client.
 *
 * Revision 1.19  2002/05/07 03:18:12  robertj
 * Added application info (name/version etc) into registered endpoint data.
 *
 * Revision 1.18  2002/05/06 00:56:37  robertj
 * Sizeable rewrite of gatekeeper server code to make more bulletproof against
 *   multithreaded operation. Especially when using slow response/RIP feature.
 * Also changed the call indexing to use call id and direction as key.
 *
 * Revision 1.17  2002/04/30 23:19:00  dereks
 * Fix documentation typos.
 *
 * Revision 1.16  2002/03/06 02:01:31  robertj
 * Fixed race condition when starting slow server response thread.
 *
 * Revision 1.15  2002/03/05 00:36:01  craigs
 * Added GetReplyAddress for H323GatekeeperRequest
 *
 * Revision 1.14  2002/03/03 21:34:50  robertj
 * Added gatekeeper monitor thread.
 *
 * Revision 1.13  2002/03/02 05:58:57  robertj
 * Fixed possible bandwidth leak (thanks Francisco Olarte Sanz) and in
 *   the process added OnBandwidth function to H323GatekeeperCall class.
 *
 * Revision 1.12  2002/03/01 04:09:09  robertj
 * Fixed problems with keeping track of calls. Calls are now indexed by call-id
 *   alone and maintain both endpoints of call in its structure. Fixes problem
 *   with calls form an endpoint to itself, and having two objects being tracked
 *   where there is really only one call.
 *
 * Revision 1.11  2002/02/04 05:21:13  robertj
 * Lots of changes to fix multithreaded slow response code (RIP).
 * Fixed problem with having two entries for same call in call list.
 *
 * Revision 1.10  2002/01/31 06:45:44  robertj
 * Added more checking for invalid list processing in calls database.
 *
 * Revision 1.9  2002/01/31 00:16:15  robertj
 * Removed const to allow things to compile!
 *
 * Revision 1.8  2001/12/15 08:08:52  robertj
 * Added alerting, connect and end of call times to be sent to RAS server.
 *
 * Revision 1.7  2001/12/14 06:40:47  robertj
 * Added call end reason codes in DisengageRequest for GK server use.
 *
 * Revision 1.6  2001/12/13 11:08:45  robertj
 * Significant changes to support slow request handling, automatically sending
 *   RIP and spawning thread to handle time consuming operation.
 *
 * Revision 1.5  2001/11/19 06:56:44  robertj
 * Added prefix strings for gateways registered with this gk, thanks Mikael Stolt
 *
 * Revision 1.4  2001/08/10 11:03:49  robertj
 * Major changes to H.235 support in RAS to support server.
 *
 * Revision 1.3  2001/08/06 07:44:52  robertj
 * Fixed problems with building without SSL
 *
 * Revision 1.2  2001/08/06 03:18:35  robertj
 * Fission of h323.h to h323ep.h & h323con.h, h323.h now just includes files.
 * Improved access to H.235 secure RAS functionality.
 * Changes to H.323 secure RAS contexts to help use with gk server.
 *
 * Revision 1.1  2001/07/24 02:30:55  robertj
 * Added gatekeeper RAS protocol server classes.
 *
 */

#ifndef __OPAL_GKSERVER_H
#define __OPAL_GKSERVER_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


#include <ptlib/safecoll.h>
#include <opal/guid.h>
#include <h323/h225ras.h>
#include <h323/transaddr.h>
#include <h323/h235auth.h>
#include <h323/h323pdu.h>
#include <h323/h323trans.h>


class PASN_Sequence;
class PASN_Choice;

class H225_AliasAddress;
class H225_EndpointIdentifier;
class H225_GatekeeperIdentifier;
class H225_ArrayOf_TransportAddress;
class H225_GatekeeperIdentifier;
class H225_EndpointIdentifier;
class H225_InfoRequestResponse_perCallInfo_subtype;
class H225_RasUsageInformation;

class H323RegisteredEndPoint;
class H323GatekeeperListener;
class H323GatekeeperServer;
class H323RasPDU;
class H323PeerElement;


class H323GatekeeperRequest : public H323Transaction
{
    PCLASSINFO(H323GatekeeperRequest, H323Transaction);
  public:
    H323GatekeeperRequest(
      H323GatekeeperListener & rasChannel,
      const H323RasPDU & pdu
    );

    virtual H323TransactionPDU * CreateRIP(
      unsigned sequenceNumber,
      unsigned delay
    ) const;

    virtual BOOL WritePDU(
      H323TransactionPDU & pdu
    );
    BOOL CheckCryptoTokens();
    BOOL CheckGatekeeperIdentifier();
    BOOL GetRegisteredEndPoint();

    virtual PString GetGatekeeperIdentifier() const = 0;
    virtual unsigned GetGatekeeperRejectTag() const = 0;
    virtual PString GetEndpointIdentifier() const = 0;
    virtual unsigned GetRegisteredEndPointRejectTag() const = 0;
    virtual unsigned GetSecurityRejectTag() const = 0;

    H323GatekeeperListener & GetRasChannel() const { return rasChannel; }

    PSafePtr<H323RegisteredEndPoint> endpoint;

  protected:
    H323GatekeeperListener & rasChannel;
};


class H323GatekeeperGRQ : public H323GatekeeperRequest
{
    PCLASSINFO(H323GatekeeperGRQ, H323GatekeeperRequest);
  public:
    H323GatekeeperGRQ(
      H323GatekeeperListener & listener,
      const H323RasPDU & pdu
    );

#if PTRACING
    virtual const char * GetName() const;
#endif
    virtual PString GetGatekeeperIdentifier() const;
    virtual unsigned GetGatekeeperRejectTag() const;
    virtual PString GetEndpointIdentifier() const;
    virtual unsigned GetRegisteredEndPointRejectTag() const;
    virtual H235Authenticator::ValidationResult ValidatePDU() const;
    virtual unsigned GetSecurityRejectTag() const;
    virtual void SetRejectReason(
      unsigned reasonCode
    );

    H225_GatekeeperRequest & grq;
    H225_GatekeeperConfirm & gcf;
    H225_GatekeeperReject  & grj;

  protected:
    virtual Response OnHandlePDU();
};


class H323GatekeeperRRQ : public H323GatekeeperRequest
{
    PCLASSINFO(H323GatekeeperRRQ, H323GatekeeperRequest);
  public:
    H323GatekeeperRRQ(
      H323GatekeeperListener & listener,
      const H323RasPDU & pdu
    );

#if PTRACING
    virtual const char * GetName() const;
#endif
    virtual PString GetGatekeeperIdentifier() const;
    virtual unsigned GetGatekeeperRejectTag() const;
    virtual PString GetEndpointIdentifier() const;
    virtual unsigned GetRegisteredEndPointRejectTag() const;
    virtual H235Authenticator::ValidationResult ValidatePDU() const;
    virtual unsigned GetSecurityRejectTag() const;
    virtual void SetRejectReason(
      unsigned reasonCode
    );

    H225_RegistrationRequest & rrq;
    H225_RegistrationConfirm & rcf;
    H225_RegistrationReject  & rrj;

  protected:
    virtual Response OnHandlePDU();
};


class H323GatekeeperURQ : public H323GatekeeperRequest
{
    PCLASSINFO(H323GatekeeperURQ, H323GatekeeperRequest);
  public:
    H323GatekeeperURQ(
      H323GatekeeperListener & listener,
      const H323RasPDU & pdu
    );

#if PTRACING
    virtual const char * GetName() const;
#endif
    virtual PString GetGatekeeperIdentifier() const;
    virtual unsigned GetGatekeeperRejectTag() const;
    virtual PString GetEndpointIdentifier() const;
    virtual unsigned GetRegisteredEndPointRejectTag() const;
    virtual H235Authenticator::ValidationResult ValidatePDU() const;
    virtual unsigned GetSecurityRejectTag() const;
    virtual void SetRejectReason(
      unsigned reasonCode
    );

    H225_UnregistrationRequest & urq;
    H225_UnregistrationConfirm & ucf;
    H225_UnregistrationReject  & urj;

  protected:
    virtual Response OnHandlePDU();
};


class H323GatekeeperARQ : public H323GatekeeperRequest
{
    PCLASSINFO(H323GatekeeperARQ, H323GatekeeperRequest);
  public:
    H323GatekeeperARQ(
      H323GatekeeperListener & listener,
      const H323RasPDU & pdu
    );

#if PTRACING
    virtual const char * GetName() const;
#endif
    virtual PString GetGatekeeperIdentifier() const;
    virtual unsigned GetGatekeeperRejectTag() const;
    virtual PString GetEndpointIdentifier() const;
    virtual unsigned GetRegisteredEndPointRejectTag() const;
    virtual H235Authenticator::ValidationResult ValidatePDU() const;
    virtual unsigned GetSecurityRejectTag() const;
    virtual void SetRejectReason(
      unsigned reasonCode
    );

    H225_AdmissionRequest & arq;