OSP Toolkit Code

---------------------------------------------------------------------------
--- COPYRIGHT (c) 2002 by TransNexus, Inc.                              ---
---                                                                     ---
--- This software is property of TransNexus, Inc.                       ---
--- This software is freely available under license from TransNexus.    ---
--- The license terms and conditions for free use of this software by   ---
--- third parties are defined in the OSP Toolkit Software License       ---
--- Agreement (LICENSE.txt).  Any use of this software by third         ---
--- parties, which does not comply with the terms and conditions of the ---
--- OSP Toolkit Software License Agreement is prohibited without        ---
--- the prior, express, written consent of TransNexus, Inc.             ---
---                                                                     ---
--- Thank you for using the OSP ToolKit(TM).  Please report any bugs,   ---
--- suggestions or feedback to support@transnexus.com                   ---
---                                                                     ---
---------------------------------------------------------------------------



---------------------------------------------------------------------------
Version 2.5.1

  * Added -D for BSAFE String Functions within Makefile
  * Initial work on port of ospopenssl.c includes SSLeay
  * New version of license agreement for LICENSE.txt
  * Added critical = False for TN extensions for OSP messages
  * Added T_strcpy, T_strcmp, T_strlen callbacks for BSAFE
  * Changed the way headers were identified within HTTP messages
  * Fixed a couple of bad references in the client auth code.
  * Changed formatting, and added osp macros for client auth code.
  * Changes in detecting header types within ospsocket.c
  * Added OSP macros in ospxml.c
  * Created separate OSPM_GETSOCKERR macro for Unix and Windows

---------------------------------------------------------------------------

Version 2.5.2

  * Added code to improve message queuing.
  * Added code to eliminate memory leaks.
  * Made the HTTP reader case-insensitive.
  * Several functions were changed to their macro equivalents.
  * Changed case on content-types within HTTP messages.
  * Eliminated some compiler warnings.
  * Implemented "subscriber" type in SourceAlternate messages.

---------------------------------------------------------------------------

Version 2.5.4

  * Added parenthesis to variables contained in macros.
  * Eliminated unnecessary macros.
  * Corrected macro OSPM_GETHOSTBYNAME to accept empty values.
  * Eliminated a potential memory leak in OSPPTransactionDelete.
  * Corrected a conditional statement in OSPPTransIdRemove.
  * Added code for ASN.1 parser to recognize boolean tags.
  * Changes were made in order to eliminate the fixed size of altinfo,
    token, and callid structures.
  * Corrected a TransNexus Extension attribute (critical should equal
    "false")
  * Corrected a buffer overflow error when constructing an enrollment
    request.
  * Added the "-function" command to the enroll's help screen.
  * Added option to compile the Toolkit with POSIX threads on Win32
    platforms.
  * Added a new module to the test_app that implements non-blocking API for
    the Toolkit.

---------------------------------------------------------------------------

Version 2.5.5

  * Changed the Toolkit to use the cryptographic algorithms
    within OpenSSL rather than BSAFE.
  * Updated Project and Make files.
  * Added "How to build the Toolkit" document.
  * New version of license agreement for LICENSE.txt

---------------------------------------------------------------------------

Version 2.5.6

  * Changed OSPPProviderNew to validate service points for correctness 
    before proceeding with creating a new provider instance.
  * Fixed handling of HTTP request to close connection - "Connection: close".
  * Fixed logic for searching available connection when HTTPMaxConnections
    has been reached.
  * Fixed a race condition in OSPPCommSignalAllConnections which could
    potentially cause a call to OSPPProviderDelete to deadlock.
  * Added initialization of random number generator engine using contents 
    of ".rnd" file expected to be found in the current directory.
  * Added Cryptogaphic Hardware Support, requires OpenSSL Engine library.
  * Replaced failure reasons with TCCodes defined in V.2

---------------------------------------------------------------------------

Version 2.6.0

  * Improved handling of HTTP and OSP codes.
  * MsgQueueDelete function now deletes mutex and cond var used by the Queue.
  * Added call start time to UsageIndication messages.
  * Added OpenSSL crypto lib support as an alternative to using existing crypto functionality.
  * Removed documentation from the build.
  * API CHANGES:
    * New type OSPTCERT defined in "include/ospdatatypes.h"
    * OSPPTransactionReportUsage function:
      * Added StartTime of type OSPTTIME
    * OSPPProviderNew function:
      * Changed the type of ospvLocalCertificate from (const void *) to (const OSPTCERT *)
      * Changed the type of ospvAuthorityCertificates from (const void *[]) to (const OSPTCERT *[])

---------------------------------------------------------------------------

Version 2.6.1

  * Upgraded TEP enrollment to use the API changes introduced in 2.6.0
  * Fixed memory leaks in the ospopenssl module.
  * Reduced compile time warnings.

---------------------------------------------------------------------------

Version 2.6.2

  * Updated the Windows project files to Compile with MultiThreaded DLL libraries, Use standard libraries and to have the ..\crypto path in the Include directives.
  * Did changes to improve the log messages.
  * Modified the Makefile and the shell script to include changes for Linux compilation.
  * Ported the GETHOSTBYNAME function for Linux.
  * This Release has been tested with MS .NET.
  * This release requires no special instructions for compiling Openssl on Windows.

---------------------------------------------------------------------------

Version 2.7

  * Support for reporting the network identifier incorporated
  * Memory leaks and bug fixes

---------------------------------------------------------------------------

Version 2.8

  * Modified the enrollment procedure to read PEM format files instead of dat. The enrollment prodedure has now been much simplified by removing the cumbersome tasks of copying the keys and editing files. It is a 3 step procedure with no practical differences for the different platforms.
---------------------------------------------------------------------------

Version 2.8.1

 * Updated test app to use PEM encoded crypto files for the following test_app.c functions - SetAuthorityCertificates, SetLocalKeys.
 * Makefile changes in the enroll and test Makefiles
---------------------------------------------------------------------------

Version 2.8.2

 * Bug fix for Linux. Problem because of trying to delete the mutex when it was locked
 * Implemeted support of SetServicePoints API in test_app, fixed a bug for this support in the Toolkit.
 * Log message changes for Linux and windows
---------------------------------------------------------------------------

Version 2.9.0

 * Implemented 2 New API's :-
 * 1. OSPPTransactionGetDestProtocol - Reports the Protocol Information at the Current destination.
 *                                     Return Values are: SIP, H323_LRQ, H323_Setup, Undefined and Unknown.
 * 2. OSPPTransactionIsDestOSPEnabled - Reports whether the destination is OSP Enabled or Not.
 *                                      Return Values are: True, False, Undefined and Unknown.
 * Implemented a compile time flag - OSP_ALLOW_DUP_TXN, to enable reuse of transactions during token validation.The purpose of this feature is to overcome the limitation where 2 token's with the same transaction id could not be validated. This compile time flag either enables or disables repeat validations. This is particularly helpful in the fail over cases when we can get a Second Call Setup message for the same call.
 * Renamed a macro - 'min', to tr_min, to avoid a conflict with the Open Source H323 library.
 * Implemented a new String comparison macro - OSPM_STRCASECMP, to ignore the case of the strings being compared. When examining the value of the critical attributes in the OSP messages, we ignore the case.As per the protocol, the values should all be lowercase, however for backward compatibility, both upper and lower case are acceptable.  
 * Modified the token Validation procedure to check for an exact match between the Calling number passed in the API and the calling number in the token.Until now an empty calling number in the API and non empty calling number in the token did not generate a Validation Failure. However now, there has to be an exact match between the 2 numbers for the Validation process to pass. A similar logic holds for the Called Number as well.  
 * Added 4 new functions to the test app - GetCallingNumber, GetCalledNumber, SetCallingNumber, SetCalledNumber. The Set functions allow the user to change the calling and called numbers on the fly. The Test App starts with the configuration in the test.cfg file as default. However, there is now an option of changing these values at run time. The Get functions display the currently configured value.  
 * Removed a Mutex Lock Error Log Message for Windows. The mutex_unlock call in function - osppHttpSetupAndMonitor, file - osphttp.c,behaves slightly differently for different OS:
    - Solaris does not seem to give a probem if this mutex is left locked or is unlocked before it is destroyed.Eitherways, it is fine.
    - Linux needs this mutex to be unlocked before it can be destroyed.
    - Windows seems to have a problem if it is unlocked before it is destroyed. Because of this 
      problem, there is an error message that pops up on Windows if this function call is made 
      before destroying the mutex. And to prevent that log message, the above mentioned function 
      call is made for all the other OS but Windows.
 * In case the client is not able to connect with the Server, the toolkit prints out log messages explaining the probable cause.The port numbers printed are now converted from network to host byte order before they are printed. This is done because of some problems seen on Linux while reporting the Port Numbers as such.
---------------------------------------------------------------------------

Version 2.9.1

 * All the macro implementation used in Production mode have been removed.
 * Removed all compilation warnings that used to pop up previously. The code now is warnings free for all the compilation modes if the openssl version being used is 0.97 or up. There will be a warning in the fn: d2i_RSAPublicKey that will appear if the openssl version is 0.96c or below.
 * Fixed a bug for 2.9.0 compilation on Windows. Turns out that 'strcasecmp' function does not work on windows. The code was modified to use 'stricmp' for case comparison on windows.
 * Modified the test_app for the following:
   1. test_app dumped core when the Private Key file - 'pkey.pem' was not present in the specified 
      directory. Fixed this to generate an error instead. 
   2. Prior to this release, multiple calls to fn 24 - TransactionDelete, did not generate any error
      in the test_app. So the following sequence - 1,23,24,24,24 or 1,24 did not generate any error 
      on the test_app interface forcing the user to wrongly beleive that transactions can be deleted 
      at will. This is now fixed, so either of the sequence mentioned above will now generate an 
      appropriate error message.  
   3. Calling fn 31 - ValidateTransaction, after calling fn 24 - DeleteTransaction dumped core. This
      has been fixed to generate an appropriate error message since calling ValidateTransaction for a 
      deleted transaction handle does not make sense. 
   4. Calling fn 32 - ReportUsageIndication, after calling fn 24 - DeleteTransaction did not generate
      any error. So the following sequence - 1,23,29,27,32,24,32 did not generate any error on the
      test_app interface forcing the user to wrongly beleive that usage can be reported even after 
      deleting the transaction.This is now fixed to generate an appropriate error message.
   5. Modified the test_app to read the Network Identifier from the CLI instead of it being
      hardcoded in the test_app as before. The ResetNetworkId function has been removed and the
      SetNetworkId can be called twice to try and attempt a change in the Network Identifier. 
 * There was a bug in the toolkit that allowed the user to Delete Transactions without Reporting Usage even if there has been a successful call to 'GetFirstDestination'. So, the following sequence of fn calls was allowed: 1,23,29, 27(Succeeds),28(Fails because only one destination was reported), 24. This is incorrect as the device should report usage if the GetFirstDestination call has succeeded.This release fixes that bug and requires the device to report usage if a call to GetFirstDestination has succeeded.
 * Fixed the compilation bug that did not let the 2.9.0 version to be run in production mode.
 * Defined OSP_SDK in 'enroll.dsp'.Without this flag defined, some the debug functionality was not getting included for the enroll utility(on windows platform), which meant missing log messages in the debug mode.
 * Fixed an ambiguos Log message for Windows. When the 'gethostbyname' function call failed on Windows, the variable - errno was not getting updated, because of which the log message indicated that there was no error.
 * Introduced a state in the transaction state machine to prevent Deletion of a Transaction while Authorization has been requested and response not received back yet. In addition to Deletion, this state facilitates the application to error out if it calls ReportUsage,GetFirstDestination or GetNextDestination API's while the Authorization Request is in progress.The same concept works for ReportUsage also. 
 * Fixed a memory leak that occured when test_app ran 1000 calls and some of the responses started timing out. The OSPM_INET_NTOA macro is removed (for both Windows and Unix implementations) and defined as a function to fix the bug.
 * Added a library - 'dl' in the makefile for Enroll and Test_app for Linux compilation in the Release Mode.It is required for some openssl functions.  
 * Fixed a bug which was introduced in the 2.8.2 release of the toolkit. The new bug caused the OSPPProviderDelete call made after attempting multiple calls to hang and never return to the application. The bug is fixed in this release. 
 * Added all pthread specific configuration (that was required on Windows) to the test.dsp, enroll.dsp and osp.dsp files. Now there is no need for manual configuration of pthreads on Windows.
 * Changed toolkit to report Translated Number (As returned in the Authorization Response) in the Usage Indication rather than the originally requested number.If the server returns no Called number in the Authorization Response or returns an empty called number in the Authorization Response, the toolkit sends the original called number (As sent in the Authorization Request) in the Usage Indication.
---------------------------------------------------------------------------

Version 2.9.2

 * Modified the test_app to run any number of test calls. Prior to this release the Option#100 in the test_app CLI ran 1000 calls. The interface now asks the user to input the number of calls that need to be run. This number can be anything as long as the maximum simltaneous transactions are not exceeded and the toolkit queue size limit is not exceeded. By default the maximum number of calls that can be run is 20,000.
 * Changed the code to eliminate all the warnings that popped up while compiling the toolkit with the SUN 'cc' compiler.
 * Changed test_app to not use 'gets'.
 * Added a section in the 'Toolkit Porting Guide' document which details the current memory allocation scheme implemented in the toolkit, and outlines how some other schemes can be used to improve the toolkit efficiency.
---------------------------------------------------------------------------

Version 2.9.3

* Implemented Subscriber Id and PIN in the Authorization Request message. The calling card information can now be passed to the Server for authorization.
* Added a new function (RequestSuggestedAuthorization, CLI function #30) to the test_app. Implemented reporting of suggested route's in the test_app. 
* Eased the restriction on reporting TC Codes in the GetNextDestination API. The toolkit now supports 0 as a valid TC Code.
* This version of the toolkit is also tested with unsigned tokens.
---------------------------------------------------------------------------

Version 2.10.0

* Implemented new API for reporting CapabilitiesIndication message.  OSPPProviderSetCapabilitiesURLs - configures
  a list of URLs.  The URLs will be used for sending the new message only.  Other OSP messages will be send to
  the service points configured using OSPPProviderNew or OSPProviderSetServicePoints.  OSPPTransactionIndicateCapabilities -
  sends the new message to one of the URLs in the list.
* Added new test cases to the test app:
  #4   tests OSPProviderSetServicePoints
  #14  tests OSPPProviderSetCapabilitiesURLs
  #37  tests a single call to OSPPTransactionIndicateCapabilities
  #101 tests multiple calls to OSPPTransactionIndicateCapabilities in parallel
* Allowed reporting source and destination Usage Indication messages without calling number.
* Fixed a bug in XML-encoding logic for empty elements with attributes.  The toolkit will correctly encode 
  empty calling number.
* Fixed a bug in OSPProviderSetServicePoints.  The function can be used for updating the list of service points
  used for sending Authorization Request and Usage Indication messages.
* Eliminated a race condition in the communication module.
* Improved resource management - quickly close TCP connection after HTTP persistence times out.
---------------------------------------------------------------------------

Version 2.10.1

* Removed a conflicting definition of OSPVersion element.  The bug was introduced in version 2.10.0
---------------------------------------------------------------------------

Version 2.11

* Modified the toolkit for the following openssl issues:
  - Crypto Hardware Initialization. 
  - Multi-threading.
  - Openssl initialization with ProviderNew: Previously, the openssl library was initialized with every
    call to ProviderNew API. This was error prone because the toolkit supports multiple calls to ProviderNew
    API. With this release the toolkit supports initialization when a call to the OSPPInit function is made.
    Thus, the OSPPInit API has changed.
* The toolkit has been modified to support multiple providers. The test_app has been modified to include a 
  new test case #102 which tests this functionality.
* Modified the toolkit to support usage reporting without an Authorization Request or a Token. A new API
  - OSPPTransactionBuildUsageFromScratch has been implemented to achieve this. In order to report usage 
    for multiple destinations the application should call this API again. 
* With this release, the unsigned mode of compilation has been removed from the toolkit. The toolkit can now
  validate both - signed and unsigned tokens in the same build. However, the application should tell the toolkit
  about the kind of algorithm (signed/unsigned/both) that the toolkit should restrict to while validating the token.
  This is done using a new parameter - ospvTokenAlgo, in the OSPPTransactionValidateAuthorization API. 
  The permissible values are - 0 for Signed token, 1 for unsigned, and 2 for both.
  Along with the ValidateAuthorization API, the following API's have also changed - OSPPTransactionInitializeAtDevice,
  OSPPTransactionReinitializeAtDevice, OSPPTransactionValidateReAuthorisation.
* Fixed a bug because of which a duration of 0 was reported in the CDR after calling OSPPTransactionRecordFailure
  API (Even if the Failure code set using the API was 1016).
* The Source,SourceDevice, Destination and DestinationDevice IP addresses(as used in the test_app)  are now configurable. 
* Three new parameter have been added to test.cfg - TOKENALGO, OUTOFRESOURCES, and HWSUPPORT.
* Request Reauthorization API has now been implemented in the test_app (test case #38).
* The toolkit now reports the Source IP address and the SourceDevice IP address in a manner different than the 
  previous releases of the toolkit. The Source IP address is now reported as SourceAlternate <type "transport">
  and the SourceDevice IP address is now reported as DeviceInfo<type "transport">.This applies to RequestAuthorization, 
  UsageIndication, CapabilityIndication, and Request Reauthorization messages. 
* This release includes an enrollment script that works on Linux and Solaris, and automates the device 
  enrollment procedure with the Server.
* Fixed a bug because of which the toolkit would crash when SSL was used for communication with the Server.Added a mutex used to protect access to the LoadCert function in ospopenssl.c file.
---------------------------------------------------------------------------

Version 2.11.1

* Modified the enroll utility to call OSPPInit function to initialize the OSP TOolkit library. Previously the enroll utility depended on SSLWrapInit function to initialize openssl. Now, it makes use of the OSPPInit function that internally initializes openssl.
* Modified the test_app to NOT create a new transaction eveytime when the BuildUsageFromScratch API is called.
* Removed the hardcoded values for token algorithm in the OSPPTransactionInitializeAtDevice and OSPPTransactionReinitializeAtDevice function.
---------------------------------------------------------------------------

Version 3.0
* The toolkit now supports look ahead routing. A look ahead route is a route embedded within the OSP token 
  and used by proxy devices to terminate the call without having to go to the OSP Server again. When a proxy
  device gets a INVITE/Setup message with a token in it, the device can validate the token, retrieve the 
  look ahead route embedded within the token and use it to terminate the call. This prevents the Proxy from
  doing a Route Authorization request. Refer to the implementation guides in the toolkit documentation for further details.
* Call Id is now optional for token validation when the token does not contain one. 
  If the token contains a CallId then the application needs to pass it in the ValidateAuthorization API. 
  If the token does not contain the call id, then the application need not pass it in the API. 
  In that case, the application can get away by passing an empty string - "".
* The toolkit is now fully SIP compliant. It now supports calling and called number in the following three 
  forms: e.164 numbers, SIP URI's, and URL's. URL's can be most useful when the application wants to report
  a e.164 number in its ENUM form.
* The toolkit has been modified to enroll with multiple servers and validate tokens from multiple OSP Servers.
  The enroll.sh script has been modified to take a list of OSP servers as input and obtain CA certificates from the different servers.
  The test application has been modified to read the multiple CA certificates and load them in the toolkit.
* The test application configuration file - test.cfg has been modified with the following configuration parameters: 
  TC Code to be reported in the usage indication, Format of the Calling Number (e.164/SIP/URL), and
  Format of the Called Number (e.164/SIP/URL).
* The following API's have changed as a result of the above mentioned changes:
  - OSPPTransactionBuildUsageFromScratch
  - OSPPTransactionInitializeAtDevice
  - OSPPTransactionRequestAuthorisation
  - OSPPTransactionValidateAuthorisation
---------------------------------------------------------------------------

Version 3.1
* The toolkit has been modified to support load balancing among the different SP's configured. Each 
  message (Authorization Req, Usage Ind, or Cap Ind) is now sent to a different OSP Server, 
  based on the load and the SP availability. For further details on the implementation, 
  refer to the toolkit documentation. 
* As a part of Load Balancing changes, the maximum number of Http Connections that can be opened
  is now made configurable in test.cfg file. Also, the maximum number of messages that can 
  be sent over a connection is made configurable. 
  This configuration is on a per Service Point basis.
* Removed compilation warnings for windows.
* Implemented multi-threading for openssl on Windows.
* Implemented a new API - OSPPTransactionModifyDeviceIdentifiers. This API is called to overwrite the 
  ospvSource/ospvSourceDevice/ospvDestination/ospvDestinationDevice that was passed in the RequestAuth/
  ValidateAuth/BuildUsageFromScratch/InitializeAtDevice APIs. This API provides the application
  with a mechanism of reporting Usage with addresses different from those that were used while calling the APIs.
* Test#102 in the test application has been removed. Test#100 has been modified to test
  multiple providers as well.  
* Modified the openssl initialization procedure to accomodate the OSP Server requirements.. 
* Implemented Performance optimizations in idle connection selection procedure and transaction handover logic.
* Fixed a potential race condition that could have occured during the shutdown phase. For details, look at comments in function - osppHttpRemoveConnection.
* As a result of the above mentioned changes, the following API's have changed:
  - OSPPProviderNew
  - OSPPProviderSetServicePoints
  - OSPPProviderSetCapabilitiesURLs
* Updated connection error and http error log messages to include IP addresses.
* Disabled hardware support for enrollment.
---------------------------------------------------------------------------

Version 3.1.1
* Removed compilation warnings on Sun compiler.
* Fixed a bug in OSPPProviderNew API because of which the toolkit would crash if the 'ospvMessageCount' was configured
  as NULL and the number of SP's exceeded one.
* The toolkit now, by default, allows deletion of a transaction even without reporting usage.If the user does not want this
  feature, the user can comment the - OSP_NO_DELETE_CHECK definition in the ospcflags.inc file (if running on Solaris/Linux), 
  or the osp.dsp file (if running on Windows).
* Modified XML parsing for optimal performance. Functions - OSPPXMLDocIsComment, OSPPXMLDocIsPI, and OSPPXMLDocIsCdata 
  only get included if flag - COMPLETE_XML_PARSING is defined.
  Since the server never includes Comments, Processing Instructions, or CData, we can safely skip these checks. 
* Fixed a bug because of which OSPPProviderDelete API, when called during the life of a connection, would give a 
  'mutex destroy failed' error.
* Fixed a race condition in the 'MsgInfo' object. The problem arose because OSPPMsgInfoWaitForMsg function could have
  been called even when the MsgInfo structure was deleted. As a fix, we now call this function only when the IsNonBlocking
  parameter of the MsgInfo structure is set to FALSE. 
* The test_app now, by default (only on Solaris), uses mtmalloc for memory allocation.
---------------------------------------------------------------------------

Version 3.1.2
* Modified the build script so that the tar file now includes one main directory.
* The header files have now been moved from the include directory to the /osp directory
  within include.
* The Makefile in the /src directory has been modified to build the toolkit directly. 
  The toolkit should be compiled by running - make in the /src directory instead of 
  running the osp_sdk_compile.ksh script.
* The makefile can also be used to build and install the osp library.
* Fixed a xml encoding bug in the ospusageind.c file.
* Added compile time flag: fPIC for compilation using gcc. 
* The ValidateAuth API has been fixed to accept NULL values for ospvCallId, 
  ospvSizeOfCallId, and ospvDetailLog parameters of the API.
* The GetFirstDestination and GetNextDestiantion APIs have been fixed to accept NULL 
  values for ospvCallId, ospvSizeOfCallId, ospvCalledNumber, ospvCalledNumber, and 
  ospvTimeLimit parameters of the API.
* The RequestAuthorization API has been fixed to accept NULL value for the ospvDetailLog
  parameter of the API.
* openssl.cnf file is now packaged with the toolkit tarball.