====================================================================
Software Name Version Number README or Module Name README 
====================================================================
Common Open Policy Server (COPS) Stack
Release 1.4.0
May 2002

====================================================================
LICENSE AND COPYRIGHT 
====================================================================
For information about licensing, please see the LICENSE file in this
directory, or http://www.vovida.org/license.html .

====================================================================
INTRODUCTION 
====================================================================
Common Open Policy Service (COPS), defined in RFC 2748,is a simple query and 
response protocol that can be used to exchange policy information between a 
policy server (Policy Decision Point or PDP) and its clients 
(Policy Enforcement Points or PEPs).The Protocol employs a client/server 
model where the client (PEP) sends requests, updates, and deletes to the 
remote server (PDP) and the PDP returns decisions back to the PEP.
The protocol uses TCP as its transport protocol and is extensible in that 
it is designed to leverage off self-identifying objects and can support 
diverse client specific information without requiring modifications to the 
protocol itself.

KEY Features - COPS Stack
--------------------------
The stack is compliant with RFC 2748 and implements all of the functionality
outlined in RFC except the support for IPv6 addressing scheme.In addition, the
stack also contains implementation of following extenstions
- COPS-PR - to support policy provisioning.


The COPS stack can be used in buliding applications such as:
1. Implementing policy based QoS framework.For example policy client is
an RSVP router that must exercise policy-based admission control over RSVP
usage.
2. Implemetating application level AAA (Authorization, Authentication and 
Accouting) functions in IP telephony network for interdomain calls. 
For eaxmple COPS in conjuctions with OSP (Open Sattelment Prorocol) to use  
third party services like clearing-houses to implement the AAA functions.

The initial motivation for the stack was to use in Softswitch, in IP Telephony, 
with OSP (Open Sattlement Protocol) to authenticate an incoming call using 
third party Clearing-houses that support OSP.
When a call is received by signalling proxy, it sends a COPS
request to PDP requesting the authentication decision.PDP using OSP then
sends request to Clearing-House(CH) along with the information needed (i.e.
the source domain of the call, number being called etc.CH authenticates the
request and sends result to PDP.PDP forms a COPS decision and sends it back to
the proxy.

Following list the COPS messages implemented by the stack grouped by their
usage.
1. Connection management - Used for establishing a session between PEP and PDP.
COPSClientOpenMsg, COPS

====================================================================
NEW FEATURES AND FUNCTIONS IN THIS RELEASE 
====================================================================
This release implements these new features and functionality:
1. COPS-PR - The framework to support COPS extenstion for policy
provisioning.Please refer to draft "http://search.ietf.org/internet-drafts/draft-ietf-rap-pr-05.txt" for more details.

2. Stack compiles and runs on 
Linux RedHat 7.1, 7.2  gcc 2.96, 
Solaris 2.8 Forte 6.0U1

====================================================================
BUG FIXES 
====================================================================

====================================================================
KNOWN LIMITATIONS
====================================================================
These limitations are known to exists in this release of the software:

Data class - implements smart strings, used to reduce the copy on 
strings. This maintains a reference to a single copy of the string, 
and makes another copy only when the string gets modified. Currently, 
the assignment from string to Data is inconsistant because of the 
automatic type converters being used in the class. This will be 
rectified in the next release.

substrings -- the substring semantics are somewhat surprising, since
they are designed to speed up access.  Thus, it is possible to try 
to access memory after it is freed accidentally via the substrings 
unless they are used carefully.

There are no known problems in the other classes.

====================================================================
GETTING STARTED
====================================================================

PLATFORM SUPPORTED
--------------------------------------------------------------------
The COPS stack will compile and run on these operating systems: 
- Linux Red Hat 7.1 , 7.2
- Sun Solaris 2.8 with Forte 6.0U1


INSTALLATION INSTRUCTIONS
--------------------------------------------------------------------
1. Download the tar ball. 
2. Untar the sip stack file using one of these commands: 
    - Linux: tar -xvzf cops-1.4.0.tar.gz 
    - Solaris: gunzip -d cops-1.4.0.tar.gz
               tar xvf cops-1.4.0

COMPILE INSTRUCTIONS
--------------------------------------------------------------------
To build the stack and sample policy server(PDP)
       make policy

To build the test programs
       make policy_test

USING THE SOFTWARE
--------------------------------------------------------------------
These are some general notes about using the software:

File copsclass.pdf file contains the class diagram for the COPS stack.

The Stack Complies with Solaris with (g++ 2.95 and earlier)

Note:Ipv6 Addressing has not been tested yet.


TESTING THE SOFTWARE
--------------------------------------------------------------------
Test cases for testing COPS stack are provided in directory 
cops-n.n.n/policy/test.A Sample policyServer is also provided
in cops-n.n.n/policy/policyServer that is needed to run all the 
test cases.Test cases are provied to test various types of COPS message.

1. Compiling the test cases
    cd cops-n.n.n
    make policy_test

2. Running the test cases
   - Make sure the policyServer is running.To run policy server
     open a new shell/terminal
     cd cops-n.n.n/policy/policyServer
     ./bin.debug.<platform>/policyServer
   -Run the test client 
     cd cops-n.n.n/policy/test
     ./bin.debug.<platform>/testClientAcceptMsg <policyServerHost:port>
     Note: port is always 3288

3.Following is a list of test programs and description.
a. testClientAcceptMsg.cxx - Create and send a Client-Accept message to PDP.
b. testClientCloseMsg.cxx - Create and send  a Client-Close message to PDP.
c. testClientOpenMsg.cxx - Create and send a Client-Open messages to PDP and
   expect a Client-Accept message from PDP. 
d. testReqMsg.cxx - Create and send a COPS Request message.
e. testKSMsg.cxx - Create and send a COPS Keep-Alive message.
f. testReportMsg.cxx - Create a send a COPS Report message.
g. testSyncStateMsg.cxx - Create and send a SyncState message.
h. testDecisionMsg.cxx - Create and send a Decision message.
i. testPrDecisionMsg.cxx - Create and send a Decision message with Policy object.
j. testPrRequestMsg.cxx - Create and send a Request message with Policy object.
    
====================================================================
SOURCE CODE INFORMATION
====================================================================
COPSMsg is the base class for different types of COPS Messages.The 
COPS message classes that implements different message types are as 
follows:

- COPSClientOpenMsg
- COPSClientAcceptMsg
- COPSClientCloseMsg
- COPSReqMsg 
- COPSDecisionMsg
- COPSDeleteMsg
- COPSReportMsg
- COPSSyncStateMsg
- COPSKAMsg

Each Message type has methods to access and set objects that are 
applicable to the message type. Different message types are defined 
as enums in COSPHeader.hxx

COPSTransceiver 
----------------
COPSTransceiver is the main class to send and receive any COPSMsg 
over a socket. 

COPSMsgParser
-------------
After receiving the raw COPS msg, it decodes the message 
and creates a message object based on the type of the message. It 
also validates the message and throws COPSBadDataException if 
message is not valid. 

Classes that implement the COPS-PR extensions
----------------------------------------------
COPSPrObjBase - Base class for all COPS-PR classes that implements the 
provisioning framework to carry the Policy data.
COPSPrEPD
COPSPrError
COPSPrErrorPRID
COPSPrGlobalError
COPSPrID
COPSPrefixPrID

COPSPrObjParser
---------------
COPSPrObjParser checks for the presence of any Provisioning data object
in the ClientSI and if found, parses the data and create an appropriate
Provisioning object.


Generating COPS Stack Documentation using Doc++
----------------------------------------------
You can use Doc++ to generate API documentation. 
Doc++ generates an alphabetical and hierarchical index of 
classes, functions, and variables. To use Doc++: 

1. Download Doc++ from http://www.zib.de/Visual/software/doc++/
2. Untar the file.
3. Locate the doc++ and docify files. These files should be in
   the /bin directory.
4. Copy the doc++ and docify files to directory where the source
   code is located.
5. Type: make doc 
6. Doc++ generated documentation will be saved in a html directory.
7. Select index.html from the html directory.

====================================================================
DIRECTORY STRUCTURE 
====================================================================
build 
----- 
This directory contains the makefiles required to build the COPS stack .

contrib 
------- 
This directory contains third party, open source software: 
libxml-2.x - Contains the libxml, an XML C library developed for the Gnome project. 

util 
----- 
This directory contains base utilities for the COPS stack. This is a 
general portability layer that makes the COPS stack more platform independent.

tools 
------
Tools needed by build setup.

doc
----
Contains the class diagrams.

policy/copsstack
-----------------
Contains the source code that implements the COPS protocol.

policy/test
-----------
Contains set of test programs to test various COPS messages.

policy/policyServer
-------------------
Contains a simple multi-threaded policy server (PDP) which can be 
extended to suite the requirement.


====================================================================
CONTRIBUTORS 
====================================================================  
This software consists of voluntary contributions made by Vovida
Networks, Inc., Cisco Systems, Inc., and many individuals.

Surendra Prajapat 

====================================================================
CONTACT INFORMATION AND WEBSITE
====================================================================
We welcome your feedback, suggestions and contributions. Contact us
via email if you have questions, feedback, code submissions, 
and bug reports.

For general inquiries - info@vovida.org

We have mailing lists for the VOCAL applications and proctocol stacks: 
VOCAL - vocal@vovida.org
COPS - cops@vovida.org
MGCP - mgcp@vovida.org
RADIUS - radius@vovida.org
RTP - rtp@vovida.org
SIP - sip@vovida.org
TRIP - trip@vovida.org
You can subscribe to the mailing lists on www.vovida.org. 

You can submit bug, patches, software contributions, and feature 
requests using Bugzilla.  Access Bugzilla from www.vovida.org. 
====================================================================
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.12.2.1 2003/03/28 05:25:51 bko Exp $
