Check Point AMON (Application Monitoring)

Transcription

1 OPSEC Check Point AMON (Application Monitoring) OPSEC SDK 6.0 May 2006

2

3 Check Point Software Technologies Ltd. All rights reserved. This product and related documentation are protected by copyright and distributed under licensing restricting their use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form or by any means without prior written authorization of Check Point. While every precaution has been taken in the preparation of this book, Check Point assumes no responsibility for errors or omissions. This publication and features described herein are subject to change without notice. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS and FAR TRADEMARKS: Check Point Software Technologies Ltd. All rights reserved. Check Point, Application Intelligence, Check Point Express, the Check Point logo, AlertAdvisor, ClusterXL, Cooperative Enforcement, ConnectControl, Connectra, CoSa, Cooperative Security Alliance, Eventia, Eventia Analyzer, FireWall-1, FireWall-1 GX, FireWall-1 SecureServer, FloodGate-1, Hacker ID, IMsecure, INSPECT, INSPECT XL, Integrity, InterSpect, IQ Engine, Open Security Extension, OPSEC, Policy Lifecycle Management, Provider-1, SecureClient, SecureKnowledge, SecurePlatform, SecuRemote, SecureXL Turbocard, SecureServer, SecureUpdate, SecureXL, SiteManager-1, SmartCenter, SmartCenter Pro, Smarter Security, SmartDashboard, SmartDefense, SmartLSM, SmartMap, SmartUpdate, SmartView, SmartView Monitor, SmartView Reporter, SmartView Status, SmartViewTracker, SofaWare, SSL Network Extender, Stateful Clustering, TrueVector, Turbocard, UAM, User-to-Address Mapping, UserAuthority, VPN-1, VPN-1 Accelerator Card, VPN-1 Edge, VPN-1 Pro, VPN-1 SecureClient, VPN-1 SecuRemote, VPN-1 SecureServer, VPN-1 VSX, VPN-1 XL, Web Intelligence, ZoneAlarm, ZoneAlarm Pro, Zone Labs, and the Zone Labs logo, are trademarks or registered trademarks of Check Point Software Technologies Ltd. or its affiliates. All other product names mentioned herein are trademarks or registered trademarks of their respective owners. The products described in this document are protected by U.S. Patent No. 5,606,668, 5,835,726, 6,496,935 and 6,850,943 and may be protected by other U.S. Patents, foreign patents, or pending applications. For third party notices, see THIRD PARTY TRADEMARKS AND COPYRIGHTS on page 135.

4

5 Contents Preface Who Should Use This Guide... 8 What Typographic Variations Mean... 9 Summary of Contents Chapter 1 Chapter 2 Chapter 3 Introduction Overview Programming Model Threads Defining the AMON Service AMON data model AMON Communication Protocol AMON Client AMON Server OPSEC OID Tree AMON API Overview Vendors Private Schema Vendors Private Schema Schema Format Definitions Block Definition Branch Definition Node Definition Simple OID Definition Table Definition Porting Private Schema Server API Functions Function Calls Oid API OidRep API AmonRequest API AmonRequestIter API AmonReply API AmonReplyIter API Server API Event Handlers AMON_REQUEST_HANDLER AMON_CANCEL_HANDLER Index...81 Table of Contents 5

6 6

7 Preface P Preface In This Chapter Who Should Use This Guide page 8 What Typographic Variations Mean page 9 Summary of Contents page 11 7

8 Who Should Use This Guide Who Should Use This Guide This document describes the AMON (Application Monitoring). This API specification is written for developers who write software to enhance the network security provided by VPN-1. It assumes that you have read the Check Point OPSEC API Specification. It also assumes that you have a basic understanding and a working knowledge of the following: system and network security the VPN-1 product system and network administration the C and/or C++ programming language the Unix or Windows operating system Internet protocols 8

9 What Typographic Variations Mean What Typographic Variations Mean The following table describes the typographic variations used in this book. TABLE P-1 Typographic Conventions Typeface or Symbol Meaning Example AaBbCc123 AaBbCc123 Save <your text>... The names of commands, files, and directories; on-screen computer output; code same as above, but with emphasis Text that appears on an object in a window Replace the angle brackets and the text they contain with your text. Lines of data or code omitted from example Edit your.login file. Use ls -a to list all files. machine_name% You have mail. session = sam_new_session (client, server); session = sam_new_session (client, server); Click on the Save button. Edit the file <FWDIR>\lib\yourfile.x x line 1 line 2... line n Preface 9

10 What Typographic Variations Mean TABLE P-1 Typographic Conventions(continued) Typeface or Symbol Meaning Example [item] [item1]... [item2] item1 item2 item3 italic The item is optional. List of optional items Choose one of the items. Specific values will be shown in italics dir [/o] dir [/o] [/w] [/s] copy infile1 infile1 + infile2 infile1 + infile2 + infile3 outfile one of addnet addapp 10

11 Summary of Contents Summary of Contents This guide contains that following chapters: Chapter Chapter 1, Introduction Chapter 2, Vendors Private Schema Chapter 3, Server API Functions Description Preface 11

12 12

13 Chapter 1 Introduction In This Chapter Overview page 14 Programming Model page 15 Defining the AMON Service page 15 AMON data model page 15 AMON Communication Protocol page 18 AMON Client page 20 AMON Server page 21 OPSEC OID Tree page 21 AMON API Overview page 29 13

14 Overview Overview Check Point s OPSEC (Open Platform for Security) integrates and manages all aspects of network security through an open, extensible management framework. Third party security applications can plug into the OPSEC framework via published application programming interfaces (APIs). Once integrated into the OPSEC framework, all applications can be configured and managed from a central point, utilizing a single Security Policy editor. This document describes the AMON (Application Monitoring), which enables third party applications to export their status to VPN-1. 14

15 Programming Model Programming Model Threads AMON API Multithread level is reentrant. This means that: Multiple threads may use the AMON API concurrently. Multiple threads may not share data generated by AMON API For more information, see Multithreaded OPSEC Applications in the Check Point OPSEC API Specification. Defining the AMON Service AMON (Application MONitoring) Service enables network applications to report their status to Check Point management. Status information is available to be fetched either by a CPMI Client or by the Check Point Status Monitoring Application (see the OPSEC CPMI API Specification ). The AMON service has 4 components: AMON data model AMON Communication Protocol AMON Server AMON Client AMON data model The data in the AMON data structure is organized in a multi-leaf tree. Each node in the tree is designated by an OID (Object ID), which is a series of non zero positive integers. In ASCII, OID is represented as a dot-separated series of numbers (e.g ). The OID is said to be "under" 1.3 or contain 1.3 (for more information about OID order see "OID Order" below). Values can be held only in leafs, and not in nodes. For example, if has a value, then 1.3 and 1 are nodes, which can t have values. An organization wishing to expose data using AMON, may want to apply to a public commitee, (IANA), to get a Private Enterprise Number in the global tree under (e.g. iso.org.dod.internet.private.enterprise). It will then be considered Chapter 1 Introduction 15

16 AMON data model as the private territory of the organization. Under that sub-tree the organization is free to expose any data it wishes. The organization can make this sub-tree public, by publishing a schema file that describes the structure of the sub-tree. To define an AMON schema one should define the OIDs in this schema and for each OID define a name, value type and display string. It is enough to define the leaves. Consider the following AMON server data tree: Figure 1-1 Example of an AMON server data tree 35 appstatus(1) 2 appname(1) appversion(2) Then the schema would look like Table 1-1 Table 1-1 Simple Schema Definition OID Name Value Type Display String 35.1 appstatus string Application status appname string Application name appversion integer Application version AMON Tables In some cases it is necessary to define multiple values for an OID. This type of schema is called a table. A table has the following properties: A table has one or more columns. Each has its own OID. One of these columns is considered as an index column, which forms the table index. The table index has a unique value for each row. The value of a specific cell can not be held in the OID of it s column; there are multiple cells in each column so the value of a cell is held in an OID. This OID is a combination of the column OID and a sub-oid which encodes the index of the new row. AMON supports only integer columns as indexes. 16

17 AMON data model The OID of columns are always placed 2 OID levels below the table OID. This is in order to allow the definition of a logical table entry entity in the schema (between the table OID and the column OIDs), whose only purpose is to specify which are the index columns. The sub-oid of the table entry is usually 1. Suppose we have the following table definitions: Table OID = Table Entry OID = 1 Column Serial OID = 1,type=integer Column Name OID = 2,type=string Column Money OID = 3,type=integer In this example Serial will serve as the index column. The schema of the table would look like Table 1-2 Table 1-2 Simple Table Schema Definition OID Name Value Type Display String Serial integer Index Name string Name Money integer Bank Account Balance OID Order and Containment OID's can be ordered in lexicographic order. One OID can contain another OID. Lexicographic Order and Containment Rules Table 1-3 Lexicographic Order and Containment Rules first OID second OID order rule containment rule 1.2.3, is before no containment 1.2.3, is before contains Chapter 1 Introduction 17

18 AMON Communication Protocol Table 1-3 Lexicographic Order and Containment Rules first OID second OID AMON Communication Protocol The Protocol order rule 1.2, is before contains , identical identical 1.2, is before 2.3 no containment The communication protocol of AMON presents a request-reply mechanism. The request is simply a list of OID's to retrieve (see AmonRequest Content on page 31). The reply is a list of reply items, each of which specifies: the OID for which it replies, the value found for this OID, the type of the value, and an optional error status (see AmonReply on page 31). Amon Scope Types The AMON protocol specifies that for each OID found in the request, the AMON server has to reply with OIDs, which are equal or "under" the OID based on the scope of the request. Amon supports three scope types (see AmonRequest Content on page 31): All client expects to get all leaves which are successors of this OID One client will only get this OID Next starting from this OID the client expects to get only the next leaf OID For example, if an AMON server has the following data tree: Figure 1-2 Example of an AMON server tree 32 1, value = Abba containment rule 2 1, value = U2 2, value = 3 18

19 AMON Communication Protocol Simple Queries Request with scope all OID = 32.1 OID = 32.2 Table 1-4 Reply Results for Scope all Value OID Value Type Status Abba 32.1 String OK U String OK Number OK Request with scope one OID = 32.1 OID = 32.2 Table 1-5 Reply Results for Scope one Value OID Value Type Status Abba 32.1 String OK None 32.2 String Not Found Request with scope next OID = 32.1 Table 1-6 Reply Results for Scope next Value OID Value Type Status Abba String OK Querying Tables Querying tables works just like any other query. The reply still consists of leaves that have values. OIDS are returned in lexicographic order column after column rather then row after row. The client knows that the OIDs are part of a table and therfore can build the table row by row. Chapter 1 Introduction 19

20 AMON Client Consider the table schema definition from Table 1-2 the Simple Table Schema Definition. Assuming the values in Table 1-7 below populate this table Table 1-7 Querying Tables Population Serial Name Money 1 George Kim Bill 5700 and that the scope is all and the request if for OID , the values that will be returned by an AMON server for Table 1-7 are liste in below. Table 1-8 Querying Tables Example Results OID Value Value Type Status Integer OK Integer OK Integer OK George String OK Kim String OK Bill String OK Integer OK Integer OK Integer OK AMON Client An AMON Client is an application, which send AMON requests to AMON servers, and handles the replies when they arrive from the server. The only AMON client is the Check Point SmartCenter Server. Check Point SmartCenter Server builds requests based on a predefined schema and exports the results through CPMI (Check Point Management Interface). The AMON client might limit the size of the reply by setting the size in the request (see AmonRequest Content on page 31). If the server sends data beyond the limit, the client might drop the reply. 20

21 AMON Server AMON Server An AMON Server is an application, which waits for AMON requests, produces replies, and sends them back to their initiator. The OPSEC package contains an API for implementing an AMON server. The server might send the whole reply at once or it might split the reply into a few replies. In the former case the server should mark the reply as last reply and in the later, it should mark the reply as not last reply (see AmonReply Content on page 31). The server might get a cancel request which notifies it that the reply for a certain request is no longer needed. In this case the server can drop the request. Figure 1-3 AMON Configuration OPSEC Application AMON Server CPMI Server Management Station AMON Client MIB CPMI Client System Status Viewer The Management Station queries the OPSEC application for its status. The Management Station provides application status info on request to CPMI Clients. OPSEC OID Tree Check Point s Private Enterprise Number is The OID is iso(1). org(3). dod(6). internet(1). private(4). enterprises(1). checkpoint(2620) Chapter 1 Introduction 21

22 OPSEC OID Tree This sub-tree has two sub-trees: Checkpoint.1 is Checkpoint products (e.g. checkpoint.1.1 is FireWall-1, checkpoint.1.2 is VPN-1) and checkpoint.2 is OPSEC which is the entry point for OPSEC applications. Figure 1-4 The Check Point sub-tree Iso(1) Org(3) Dod(6) Internet(1) Private(4) Enterprises(1) Checkpoint(2620) Products(1) Opsec(2) OpsecGenericStatus Schema Figure 1-5 opsecgenericstatus Fields opsec (2) opsecstatus (1) opsecgenericstatus (1) opseccvpstatus (2) opsecufpstatus (3) opsecleastatus (4) opsecelastatus (5) opsecsamstatus (6) opseccpmistatus (7) 22

23 OPSEC OID Tree Entry point OID Table 1-9 opsecgenericstatusfields Name OID Value Type OPSEC VT Type Description statusok 1 Intege r OPSEC_VT_I32BIT 0 if the status of the application is OK, otherwise non-zero. statusdescription 2 String OPSEC_VT_STRING Text description of the status of the application. opsecvendor 3 String OPSEC_VT_STRING Text description of the status of the application. opsecproduct 4 String OPSEC_VT_STRING The product name. opsecproductversion 5 String OPSEC_VT_STRING The product version. opsecsdkversion 6 String OPSEC_VT_STRING The OPSEC SDK version. opsecsdkbuildnumbe r 7 Intege r opsecappuptime 8 Intege r OPSEC_VT_UI32BIT OPSEC_VT_UI32BIT OPSEC SDK build number. The number of seconds since the application started as returned by the ANSII C function time(). Chapter 1 Introduction 23

24 OPSEC OID Tree OpsecCvpStatusSchema Entry point OID Table 1-10 opseccvpstatusfields Name OID Value Type OPSEC VT Type Description cvpitemsmodified 1 Integer OPSEC_VT_UII32BIT The number of the sessions that modified the content. cvpitemsnotmodified 2 Integer OPSEC_VT_UII32BIT The number of the sessions that did not modify the content. cvpitemsreplaced 3 Integer OPSEC_VT_UII32BIT The number of the sessions that replaced the content. cvpitemsnotsafe 4 Integer OPSEC_VT_UII32BIT The number of the sessions where the content was not safe. cvpitemssafe 5 Integer OPSEC_VT_UII32BIT The number of session where the content was safe. OpsecUfpStatusSchema Entry point OID

25 OPSEC OID Tree Figure 1-6 opsecufpstatus (3) ufptable (1) ufpentry (1) OpsecUfpStatus Schema Image Table entry point OID Table 1-11 ufpentry Fields Name OID Value Type OPSEC VT Type Description ufpindex 1 Integer OPSEC_VT_UI32BIT Index for the table. ufpcategoryname 2 String OPSEC_VT_STRING The category name. ufpcategory Matched 3 Integer OPSEC_VT_UI32BIT The number of requests that matched this category. OpsecLeaStatusSchema Entry point OID Figure 1-7 opsecleastatus (4) leatable (1) leaentry (1) OpsecLeaStatusSchema Image Chapter 1 Introduction 25

26 OPSEC OID Tree Table entry point OID Table 1-12 leaentry Fields Name OID Value Type OPSEC VT Type Description leaindex 1 Integer OPSEC_VT_UI32BIT Index for the table. leaserver 2 String OPSEC_VT_STRING The host name of the LEA server. lealogsread 3 Integer OPSEC_VT_UI32BIT The number of logs read from this server. OpsecElaStatusSchema Entry point OID Figure 1-8 opsecelastatus (5) elatable (1) elaentry (1) OpsecElaStatus Schema Image Table entry point OID Table 1-13 ela Entry Fields Name OID Value Type OPSEC VT Type Description elaindex 1 Integer OPSEC_VT_UI32BIT Index for the table. elaserver 2 String OPSEC_VT_STRING The host name of the ELA server. elalogswritten 3 Integer OPSEC_VT_UI32BIT The number of logs written to this server. 26

27 OPSEC OID Tree OpsecSamStatus Schema Entry point OID Figure 1-9 opsecsamstatus (6) samtable (1) samentry (1) OpsecSamStatus Schema Image Table entry point OID Table 1-14 samentry Fields Name OID Value Type OPSEC VT Type Description samindex 1 Integer OPSEC_VT_UI32BIT Index for the table. samserver 2 String OPSEC_VT_STRING The host name of the SAM server. saminhibitreq 3 Integer OPSEC_VT_UI32BIT The number of Inhibit requests to this server. samnotifyreq 4 Integer OPSEC_VT_UI32BIT The number of Notify requests to this server. samdeletereq 5 Integer OPSEC_VT_UI32BIT The number of Delete requests to this server. samcancelreq 6 Integer OPSEC_VT_UI32BIT The number of Cancel requests to this server. samclosedconn 7 Integer OPSEC_VT_UI32BIT The number of Close Connection requests to this server. OpsecCpmiStatus Schema Entry point OID Chapter 1 Introduction 27

28 OPSEC OID Tree Figure 1-10 opseccpmistatus (7) cpmitable (1) cpmientry (1) OpsecCpmiStatus Schema Image Table entry point OID Table 1-15 cpmientry Fields Name OID Value Type OPSEC VT Type Description cpmiindex 1 Integer OPSEC_VT_UI32BIT Index for the table. cpmiserver 2 String OPSEC_VT_STRING The host name of the CPMI server. cpmidbmode 3 String OPSEC_VT_STRING The Database Open mode eg. Write, Read Only etc. OPSEC Schema Mandatory Fields OPSEC defines mandatory fields which vendors should support if they support AMON in their applications. The vendors should support the opsecgenericstatus variables as well as any other supported OPSEC service status variables. For example, if the vendor supports ELA and CVP, they should also support opseccvpstatus and opsecelastatus variables. Vendors might also support their own schema (see Vendors Private schema on page 36). Note - OIDs that represent counters assumed to reset their count at application start. 28

29 AMON API Overview AMON API Overview AMON Server Application Events The AMON Server responds to the events listed in Table 1-16 A response is handled by the event handler (callback) function set in the call to opsec_init_entity for that event. Table 1-16 AMON Server Events Event Description New request arrived Cancel request arrived Handler AMON_REQUEST_HANDLER AMON_CANCEL_HANDLER Reference Event Handler for the AMON_REQUEST event page 29 Event Handler for the AMON_CANCEL_REQUEST event page 29 Event Handler Functions The event handlers functions are written by the AMON Server developer. These handlers should return one of the following values (for more about information about Event handlers see Event Handlers on page 73). Table 1-17 Values Returned by Event Handlers Value OPSEC_SESSION_OK OPSEC_SESSION_END OPSEC_SESSION_ERR Meaning The session can continue. The session will be closed. The session will be closed because of an error. An AMON Server s main function should proceed as illustrated below: Chapter 1 Introduction 29

30 AMON API Overview Figure 1-11 AMON Server Application Structure initialize OPSEC environment initialize AMON Server entity start the AMON Server start the main loop Handler for Event #1 main loop EVENT #1 EVENT #2 Handler for Event #2 free the AMON Server entity free OPSEC environment 30

31 AMON API Overview Data Structures Table 1-18 AMON use the following objects as its data structures: Object Definition page AmonRequest AmonReply Holds the request from the client to the server. Holds the reply from the server to the client. page 31 page 31 OidRep Building blocks for AmonReply. page 32 Oid Object that represent OID. page 32 Opsec_value_t Object to hold many types of data. page 32 Note - All of these objects have functions to create, destroy and manipulate them AmonRequest AmonRequest includes the following information: list of OID's (one or more). search scope (see below) - the AMON client adds to each request a search scope. This might be one of the following values: AmonScope_GetAll client expects to get all leaf successors of this OID. AmonScope_GetOne client expects to get this OID only. AmonScope_GetNext client expects to get only the next leaf of this OID size limit - client expect server to send in the reply OID's up to this limit (Default = 500; 0 = no limit) AmonReply AmonReply includes the following information: List of OidRep's (one or more) see OidRep Content (page 17). Error code for the whole reply. One of the following values AmonError_OK AmonError_Fail Chapter 1 Introduction 31

32 AMON API Overview Last reply marker (see below) LastReply_False LastReply_True Server should send a reply to the client with one of the following: LastReply_False - if the reply for a request is partial result and more replies will be sent soon for a that request. LastReply_True - if the reply is complete. OidRep OidRep includes the following information: Oid Error code for this OID- this should be one of the following values: OidErr_Ok OidErr_NotFound Value see below opsec_value_t Opsec_value_t AMON use virtual types of data with objects to hold these data types. The table below lists all the valid types used by AMON: Table 1-19 Valid Types of Data Used by Amon Virtual Type Actual Type Comments OPSEC_VT_NONE OPSEC_VT_I16BIT OPSEC_VT_I32BIT OPSEC_VT_I64BIT OPSEC_VT_UI16BIT OPSEC_VT_UI32BIT OPSEC_VT_UI64BIT None Signed short Signed integer Signed 64 bit number Unsigned short Unsigned integer Unsigned 64 bit number 32

33 AMON API Overview Table 1-19 Valid Types of Data Used by Amon Virtual Type Actual Type Comments OPSEC_VT_IP IP address Network Order OPSEC_VT_BUFF OPSEC_VT_STRING OPSEC_VT_IPV6 For further information on opsec_value_t refer to Opsec Value Tyes in the OPSEC API Specification. AMON Client Tool The OPSEC SDK Next Generation includes amon_client, an AMON testing tool that enables testing of an AMON Server without VPN-1. The tool is contained in the OPSEC SDK Next Generation package. The Amon Client queries the Amon Server and prints the results to stderr. Syntax amon_client [options] <list of oid s> Array of characters NULL terminated buffer Type that represents Ipv6 Chapter 1 Introduction 33

34 AMON API Overview Table 1-20 Argument Options Options (Cont.) list of OID s AMON Client Tool Meaning Any of the following: Option Meaning -s scope One of the following All client expects to get all leaves which are successors of this OID One client will only get this OID Next starting from this OID the client expects to get only the next leaf OID -t timeout Client side timeout for all operations (in mili-seconds). The default is 0, no time out. -r reply mode One of the following all accept all the results (default) partial accept partial results -l size limit The default is means no size limit. -h host The Server s IP address in dotted format. The default is p port The Server s Port. The default is The list of OID s to retrieve. 34

35 Chapter 2 Vendors Private Schema In This Chapter Vendors Private Schema page 36 Schema Format Definitions page 36 Block Definition page 38 Branch Definition page 39 Node Definition page 40 Simple OID Definition page 41 Table Definition page 43 Porting Private Schema page 46 35

36 Vendors Private Schema Vendors Private Schema AMON allows vendors to export their private schema. This schema needs to be imported into the Check Point schema before it can be used. After it has been imported, based on this schema, the AMON client (ie, VPN-1 SmartCenter Server) will query the AMON server. To import a private schema definition to Check Point s schema (which resides on the VPN-1 SmartCenter Server), AMON supports a private schema file with a specific format. An import tool uses this file as an input to port the schema (with a compatible format) into the Check Point schema (see Porting Private Schema below). Schema Format Definitions The schema file is composed of a file header and one or more blocks. Each block represents a complete product schema definition. This definition can be referenced using its identifier, from the Policy Editor when the product is defined as an OPSEC application (see Defining OPSEC applications in the Check Point SmartCenter Guide ). Blocks are composed of one or more branches. Each branch contains definitions of simple OIDs, nodes and tables. Nodes may contain simple OIDs, other nodes and tables. Tables contain columns. Tokens are composed of letters, digits and underscore characters. All white space characters except newline are ignored unless they are placed in quoted strings ( ). Tokens are separated by comma characters (,). Token s identifier have to be unique within the scope of the schema file. 36

37 Schema Format Definitions For example File Header Block Branch Simple-OID and/or Node and/or Table End-Branch End-Block Table 2-1 Header Tokens Token Argument Meaning of Comments s START-FILE-HEADE None R FILE-TYPE File Type The type of this file. Should be: MIB-DEFINITION. VERSION Version The version of this file. Should be: 5.0. END-FILE-HEADER None START-FILE-HEADER FILE-TYPE, MIB-DEFINITION VERSION, 5.0 END- FILE-HEADER Chapter 2 Vendors Private Schema 37

38 Block Definition Block Definition Table 3: Token Meaning of Comments START-BLOC K BLOCK-NAM E None Identifier Identifier for this block. The one word token that should start with a lower case letter. Display String String to display with this block. A quoted string. IMPLEMENT Implement Comma separated list of the OPSEC APIs that the application supports. One or more of: CVP, UFP, LEA, ELA, SAM, CPMI. END-BLOCK None For example: START-BLOCK BLOCK-NAME, mystatus, My Status IMPLEMENT,CVP, CPMI, ELA END-BLOCK 38

39 Branch Definition Branch Definition Table 2-1 Branch Tokens Token Meaning of Comments START-BRA NCH END-BRAN CH Identifier Identifier for this branch. The one word token that should start with a lower case letter. Display String OID None For example START-BLOCK String to display with this branch. The absolute OID of the branch. BLOCK-NAME, mystatus, My Status IMPLEMENT,CVP, CPMI, ELA A quoted string. START-BRANCH, myfirstbranch, My First Branch, END-BRANCH END-BLOCK Chapter 2 Vendors Private Schema 39

40 Node Definition Node Definition Table 2-2 NODE Tokens Token Meaning of Comments START-NO DE END-NODE Identifier An identifier for this node. The one word token, should start with lower case letter. Display String OID None For example START-BLOCK The string to display with this branch. The relative OID of the Node. BLOCK-NAME, mystatus, My Status IMPLEMENT,CVP, CPMI, ELA A quoted string. START-BRANCH, myfirstbranch, My First Branch, START-NODE, myfirstnode, My First Node, 4 END-NODE END-BRANCH END-BLOCK 40

41 Simple OID Definition Simple OID Definition Table 2-3 Simple OID Tokens Token Meaning of Comments SIMPLE-O ID Identifier An identifier for this OID. The one word token, should start with lower case letter. Display String OID The string to display with this OID. The relative OID of this OID. A quoted string. Value Type The value type. One of: UINT16, INT16, UINT32, INT32, UINT64, INT64, IP, STRING Mandatory Optional attribute: Is this OID mandatory or optional. One of: MANDATORY, OPTIONAL Default = MANDATORY Chapter 2 Vendors Private Schema 41

42 Simple OID Definition For example START-BLOCK BLOCK-NAME, mystatus, My Status IMPLEMENT,CVP, CPMI, ELA START-BRANCH, myfirstbranch, My First Branch, START-NODE, myfirstnode, My First Node, 4 SIMPLE-OID, myfieldname, My FieldName, 1, STRING SIMPLE-OID, myfieldnumber, My Field Number, 2, UINT16 END-NODE SIMPLE-OID, myname, My Name, 10, STRING, OPTIONAL SIMPLE-OID, mynumber, My Number, 11, UINT32 END-BRANCH END-BLOCK 42

43 Table Definition Table Definition Table 2-4 TABLE Tokens Token Meaning of Comments START -TABL E Table Identifier Table Display String OID Entry Identifier Entry Display String OID An identifier for this table. The string to display with this table name. The relative OID. An identifier for this table entry. The string to display with this entry name. The relative OID to the table entry. The one word token, should start witha lower case letter. A quoted string. The one word token, should start with lower case letter. A quoted string. Chapter 2 Vendors Private Schema 43

44 Table Definition Table 2-4 COLU MN END-T ABLE Identifier Display String OID TABLE Tokens The identifier for this column. The string to display with this OID. The relative OID of this OID. The one word token, should start with lower case letter. A quoted string Value Type The value type. One of: UINT16, INT16, UINT32, INT32, STRING. Index None For index column this is the index number. Must be an integer. 0 means not an index column. 44

45 Table Definition For example START-BLOCK BLOCK-NAME, mystatus, My Status IMPLEMENT,CVP, CPMI, ELA START-BRANCH, myfirstbranch, My First Branch, START-NODE, myfirstnode, My First Node, 4 SIMPLE-OID, myfieldname, My Node Name, 1, STRING SIMPLE-OID, myfieldnumber, My Node Number, 2, UINT16 START-TABLE, nodetablename, My Node Table, 3, nodeentryname, My Node Entry, 1 COLUMN, mytableindex, Index, 1, UINT32, 1 COLUMN, myname, My Name, 2, STRING, 0 COLUMN, mynumber, My Number, 3, INT32, 0 END-TABLE END-NODE SIMPLE-OID, myname2, My Name2, 10, STRING, OPTIONAL SIMPLE-OID, mynumber2, My Number2, 11, UINT32 START-TABLE, othertablename, My Table, 21, otherentryname, My Entry, 1 COLUMN, otherindex, Other Index, 1, UINT32, 1 COLUMN, othername, My Other Number, 2, INT32, 0 END-TABLE END-BRANCH END-BLOCK Chapter 2 Vendors Private Schema 45

46 Porting Private Schema Porting Private Schema In order to port the AMON schema (definition described in Schema Format Definitions ) to a Check Point schema, a command-line tool is supplied in the VPN-1 package called "amon_import". Run it on SmartCenter Server with root permissions. Its output is a modification of the Check Point schema that takes effect after re-running the Check Point AMON (Application Monitoring) service. Usage The format of the command line is as follows: amon_import [-force] [-nochange] [-delete] input_file Table 2-5 parameter -nochange -force -delete input_file amon_import parameters Do the process,leave the Check Point schema unchanged. Force a possible override of an existing AMON schema. Delete the input_file schema from the Check Point schema. The AMON schema file name. The program exits with a non-zero code upon failure. The default invocation has no parameters and ports the scheme for the first time. If the program is run again, it will exit with error, with a prompt stating that the schema was already ported. To delete the existing entry run the program with the -delete parameter. To force an override of the existing entry, use the -force parameter. Use the -nochange parameter to check the validity of the input file as well as the validity of the whole porting process. Note - Because it uses the input file name as an entry in the scheme, don't use the tool with different files (containing same block names) without deleting the old entry first. 46

47 Chapter 3 Server API Functions In This Chapter Function Calls page 48 Oid API page 48 OidRep API page 56 AmonRequest API page 62 AmonRequestIter API page 63 AmonReply API page 65 AmonReplyIter API page 70 Server API page 71 Event Handlers page 73 AMON_REQUEST_HANDLER page 73 AMON_CANCEL_HANDLER page 74 47

48 Function Calls Function Calls This section describes the functions provided by the OPSEC AMON API. Oid API The following functions enable creation, deletion and other manipulations on Oid objects. oid_create Create oid object. int oid_create(oid **oid, const OidNum *oid_arr, unsigned int oid_arr_len); Table 3-1 oid_create s oid oid_arr oid_arr_length a pointer to hold the new oid number-array representation of oid length of the array EO_OK if successful. EO_ERROR otherwise. oid_create_from_string Create oid object from string. int oid_create_from_string(oid **oid, const char *oid_str); 48

49 Oid API Table 3-2 oid_create_from_string s oid oid_str a pointer to hold the new oid a string representation of oid (e.g. a.b.c.d) EO_OK if successful. EO_ERROR otherwise. oid_duplicate Duplicate (create) oid object from another oid. int oid_duplicate(oid **dst_oid, const Oid *src_oid); Table 3-3 oid_duplicate s dst_oid src_oid a pointer to hold the new oid oid to duplicate EO_OK if successful. EO_ERROR otherwise. Note - The caller should destroy the duplicated oid, using oid_destroy. oid_destroy Destroy oid object. void oid_destroy(oid *oid); Chapter 3 Server API Functions 49

50 Oid API Table 3-4 oid_destroy s oid Oid object None. oid_to_string Return the string representation of the oid on success, else NULL. char * oid_to_string(const Oid *oid); Table 3-5 oid_to_string s oid Oid object return the string representation of the oid on success, else NULL Note - The caller should free this string using opsec_free(). oid_to_array Convert oid to array of numbers. int oid_to_array(const Oid *oid, OidNum **oid_arr, unsigned int *oid_arr_len); 50

51 Oid API Table 3-6 oid_to_array s oid oid_arr oid_arr_length oid object a pointer to hold the Number-array representation of oid a pointer to hold array length EO_OK if successful. EO_ERROR otherwise. Note - The caller should free this array using opsec_free(). oid_get_length Return oid length. unsigned int oid_get_length(const Oid *oid); Table 3-7 oid_get_length s oid oid object The size of the array that is required to hold this oid. oid_compare Lexicographical comparison between two oid's. int oid_compare(const Oid *left, const Oid *right); Chapter 3 Server API Functions 51

52 Oid API Table 3-8 oid_compare s left right left oid right oid 0 if not different (equal), < 0 if left is before right > 0 if left is after right oid_concat Concatenate oid2 to oid1. int oid_concat(oid* oid1, const Oid* oid2); Table 3-9 oid_concat s oid1 oid2 oid object oid object EO_OK if successful. EO_ERROR otherwise. oid_contain Check if left oid number contains right oid. For example: 1.2.3, no containment 1.2.3, right contains left , left contains right 52

53 Oid API 1.2.3, identical eoidcontain oid_contain(const Oid* left, const Oid* right); Table 3-10 oid_contain s left right left oid right oid eoidcontain values. Possible values for containment: Table 3-11 eoidcontain values value OidContain_NoContainment OidContain_LeftContainRight OidContain_RightContainLeft OidContain_Identical description not containment between the oid s left oid contain right oid right oid contain left oid oids are identical oid_prefix Returns the prefix of oid on success. int oid_prefix(const Oid* oid, unsigned int num_of_elems, Oid** prefix_oid); Chapter 3 Server API Functions 53

54 Oid API Table 3-12 oid_prefix s oid num_of_elems prefix_oid Oid object number of elements in prefix if num_of_elems > oid_length then all oid will be returned in prefix_oid pointer to hold the prefix EO_OK if successful. EO_ERROR otherwise Note - Caller should destroy prefix_oid using oid_destroy. oid_suffix Returns the suffix of oid on success. int oid_suffix(const Oid* oid, unsigned int num_of_elems, Oid** suffix_oid); 54

55 Oid API Table 3-13 oid_suffix s oid num_of_elems suffix_oid Oid object number of elements in suffix if num_of_elems > oid_length then all oid will be returned in suffix_oid pointer to hold the suffix EO_OK if successful. EO_ERROR otherwise Note - Caller should destroy prefix_oid using oid_destroy. oid_chop_left Chop n elements from left of oid. void oid_chop_left(oid* oid, unsigned int num_of_elems); Table 3-14 oid_chop_left s oid num_of_elems Oid object number of elements to chop if num_of_elems > number of elements in oid then oid length will be 0 None. oid_chop_right Chop n elements from right of oid. Chapter 3 Server API Functions 55

56 OidRep API void oid_chop_right(oid* oid, unsigned int num_of_elems); Table 3-15 oid_chop_right s oid num_of_elems Oid object number of elements to chop if num_of_elems > number of elements in oid then oid length will be 0 None. oid_element Returns the 'index' element in oid. int oid_element(const Oid *oid, unsigned int index); Table 3-16 oid_element s oid index Oid object the nth element to retrieve the n-th element if exists (>=0), else -1 OidRep API The following functions enable creation, deletion and other manipulations to OidRep objects. 56

57 OidRep API oid_reply_create Create oid reply object. int oid_reply_create(oidrep **oid_rep); Table 3-17 oid_reply_create s oid_rep OidRep object EO_OK if successful. EO_ERROR otherwise. oid_reply_destroy Destroy OidRep object. void oid_reply_destroy(oidrep *oid_rep); Table 3-18 oid_reply_destroy s oid_rep OidRep object None. oid_reply_get_oid Returns a reference to the oid of the OidRep object const Oid * oid_reply_get_oid(const OidRep *oid_rep); Chapter 3 Server API Functions 57

58 OidRep API Table 3-19 oid_reply_get_oid s oid_rep OidRep object A pointer to (reference) Oid on success, otherwise NULL. Note - Do not try to free this pointer. oid_reply_get_opsec_value Returns reference to opsec_value object in oid_rep. const opsec_value_t *oid_reply_get_opsec_value (const OidRep *oid_rep); Table 3-20 oid_reply_get_value s oid_rep OidRep object Pointer to (reference) opsec_value_t on success, otherwise NULL. Note - Do not try to free this pointer. opsec_value_t should be parsed and acced using opsec_value api (see the OPSEC.pdf) for amon supported value types see AMON Communication Protocol on page 18 oid_reply_get_error Return error status of OidRep object. eoiderror oid_reply_get_error(const OidRep *oid_rep); 58

59 OidRep API Table 3-21 oid_reply_get_error s oid_rep OidRep object Return one of the eoiderror values from Table 3-22 below. Table 3-22 value OidErr_OK oid_reply_get_error codes description the status of this oid reply is OK OidErr_NotFound this oid was not found oid_reply_get_all Return all the content of OidRep object. void oid_reply_all(const OidRep *oid_rep, const Oid **oid, const opsec_value_t **value, eoiderror *err) Chapter 3 Server API Functions 59

60 OidRep API Table 3-23 oid_reply_get_all s oid_rep oid value err OidRep object a pointer to hold the oid a pointer to hold the value a pointer to hold the error None. Note - Do not try to free oid and value. oid_reply_set_oid Sets the oid in OidRep. int oid_reply_set_oid(oidrep *oid_rep, const Oid *oid); Table 3-24 oid_reply_set_oid s oid_rep oid OidRep object the oid to set in the OidRep EO_OK if successful. EO_ERROR otherwise. oid_reply_set_opsec_value Sets opsec_value_t object to OidRep object. 60

61 OidRep API int oid_reply_set_opsec_value(oidrep *oid_rep, const opsec_value_t *value); Table 3-25 oid_reply_set_opsec_value s oid_rep value OidRep object the value to set EO_OK if successful. EO_ERROR otherwise. oid_reply_set_error set error of oid object in OidRep object void oid_reply_set_error(oidrep *oid_rep, eoiderror err); Table 3-26 oid_reply_set_error s oid_rep err OidRep object the error to set None. oid_reply_create_with_all Creates OidRep object with all setting. int oid_reply_create_with_all(oidrep **oid_rep, const Oid *oid, const opsec_value_t *value, eoiderror err); Chapter 3 Server API Functions 61

62 AmonRequest API Table 3-27 oid_reply_create_with_all s oid_rep oid value err a pointer to hold the new created OidRep object oid that will be set to the created OidRep value that will be set to the created OidRep error that will be set to the created OidRep EO_OK if successful. EO_ERROR otherwise. AmonRequest API The following functions enable you to parse AmonRequest objects. amon_request_get_num_of_oids Returns the number of OIDs in the specified request. unsigned int amon_request_get_num_of_oids(const AmonRequest *req); Table 3-28 amon_request_get_num_of_oids s req A pointer to the request. The number of OIDs if successful, otherwise 0. amon_request_get_scope Returns the search scope of the request. eamonscope amon_request_get_scope(const AmonRequest *req); 62

63 AmonRequestIter API Table 3-29 amon_request_get_scope s req A pointer to the request. One of the following values: Table 3-30 amon_request_get_scope return values Value AmonScope_GetAll AmonScope_GetOne AmonScope_GetNext Meaning this oid and all its sub tree oid's one oid only next oid only amon_request_get_size_limit unsigned int amon_request_get_size_limit(const AmonRequest *req); Table 3-31 amon_request_get_size_limit s req A pointer to the request. Return the size_limit (max oid's) of the request. AmonRequestIter API This set of functions allow iteration on the AmonRequest object. amon_request_iter_create Creates iterator on request. Chapter 3 Server API Functions 63

64 AmonRequestIter API int amon_request_iter_create(amonrequest *req, AmonRequestIter **iter); Table 3-32 amon_request_iter_create s req iter A pointer to the request. A pointer to be set to the request iterator. EO_OK on success. EO_ERROR otherwise. Note - Note: caller should destroy iter using amon_request_iter_destroy amon_request_iter_next Iterate on all oid s in AmonRequest. const Oid * amon_request_iter_next(amonrequestiter *iter); Table 3-33 amon_request_iter_next s iter A pointer to the request iterator. On the first call, the first oid in the request is returned. For each succeeding call, the function iterates and the next oid is retrieved. NULL if error or if the last oid has been returned. amon_request_iter_destroy Destroy AmonRequestIter. 64

65 AmonReply API void amon_request_iter_destroy(amonrequestiter *iter); Table 3-34 amon_request_iter_destroy s iter A pointer to the request iterator. None. AmonReply API The following functions enable creation, deletion, parsing, setting and get value from AmonRequest objects. Contains: list of OidRep's number of OidRep's in the list last reply marker reply status amon_reply_create Create AmonReply object int amon_reply_create(amonreply **rep); Chapter 3 Server API Functions 65

66 AmonReply API Table 3-35 amon_reply_create s rep pointer to hold the AmonReply object EO_OK if successful. EO_ERROR otherwise. Note - Note: the caller should destroy this reply using amon_reply_destroy. amon_reply_destroy Destroy AmonReply object. void amon_reply_destroy(amonreply *rep); Table 3-36 amon_reply_create s rep pointer to AmonReply object None. amon_reply_add_oid Add oid to reply. int amon_reply_add_oid(amonreply *rep, const OidRep *oid_rep); 66

67 AmonReply API Table 3-37 amon_reply_add_oid s rep oid_rep the reply which the oid will be added to OidRep object to add to the reply EO_OK if successful. EO_ERROR otherwise. amon_reply_remove_oid Remove oid from reply. void amon_reply_remove_oid(amonreply *rep, const Oid *oid); Table 3-38 amon_reply_remove_oid s rep oid AmonReply object which the oid will be removed from the oid to remove None. amon_reply_get_num_of_oids Returns the number of oid's in a reply. unsigned int amon_reply_get_num_of_oids(const AmonReply *rep); Chapter 3 Server API Functions 67

68 AmonReply API Table 3-39 amon_reply_get_num_of_oids s rep AmonReply object returns number of oid's amon_reply_get_error Gets error of reply from AmonReply object. eamonerror amon_reply_get_error(const AmonReply *rep); Table 3-40 amon_reply_get_error s rep AmonReply object AmonError_OK when the reply is OK. AmonError_Fail the server failed to reply to a specific request. amon_reply_set_error Sets error of reply in AmonReply object. void amon_reply_set_error(amonreply *rep, eamonerror reply_err); 68

69 AmonReply API Table 3-41 amon_reply_set_error s rep reply_err AmonReply Object refer to amon_reply_get_error above None. amon_reply_get_last_reply_mark Gets last reply marker from AmonReply object. elastreply amon_reply_get_last_reply_mark(const AmonReply *rep); Table 3-42 amon_reply_get_last_reply_mark s LastReply_False LastReply_True This is not the last reply. This is the last reply. None. amon_reply_set_last_reply_mark Sets last reply marker in AmonReply object. void amon_reply_set_last_reply_mark(amonreply *rep, elastreply last_rep_mark); Chapter 3 Server API Functions 69

70 AmonReplyIter API Table 3-43 amon_reply_set_last_reply_mark s rep last_rep_mark AmonReply Object the last reply marker None. AmonReplyIter API This set of functions allow iteration on the AmonReply object. amon_reply_iter_create Creates iterator on reply. int amon_reply_iter_create(amonreply *rep, AmonReplyIter **iter); Table 3-44 amon_reply_iter_create s rep iter AmonReply Object pointer to hold the iterator EO_OK if successful. EO_ERROR otherwise. Note - Caller should destroy iter using amon_reply_iter_destroy. amon_reply_iter_next Iterate on all OidRep objects in AmonReply. 70

71 Server API const OidRep * amon_reply_iter_next(amonreplyiter *iter); Table 3-45 amon_reply_iter_next s iter pointer to hold the iterator On the first call, the first oid in the request is returned. For each succeeding call, the function iterates and the next oid is retrieved. NULL if error or if the last oid has been returned. amon_reply_iter_destroy Destroy AmonRequestIter. void amon_reply_iter_destroy(amonreplyiter *iter); Table 3-46 amon_reply_iter_destroy s iter AmonReplyIter object None. Server API The following functions enable interaction with an amon client. amon_reply_send Sends the reply on the session. Chapter 3 Server API Functions 71

72 Server API int amon_reply_send(opsecsession *session, AmonReply *rep, AmonReqId id); Table 3-47 amon_reply_send s session rep id opsec session the reply to send the id of the request that this reply answers EO_OK if successful. EO_ERROR otherwise. 72

73 Event Handlers Event Handlers This section describes the functions that need to be written in order to implement an AMON Server. All of these functions take a pointer to an OpsecSession as their agrument. The memory allocated for the function s is managed by the OPSEC environment, and the s hold valid data only during the execution of the handler function. For this reason do not save a static pointer to this data to use after the handler function returns. AMON_REQUEST_HANDLER This function is called when a new request arrives from the client. eopsechandlerrc amon_request_handler(opsecsession *session, AmonRequest *req, AmonReqId id); Table 3-48 amon_request_handler session req id opsec session the request that arrived from the amon client id of the request Return Value OPSEC_SESSION_OK OPSEC_SESSION_ERR OPSEC_SESSION_END Chapter 3 Server API Functions 73

74 AMON_CANCEL_HANDLER AMON_CANCEL_HANDLER This function is called when a cancel request arrives from the client. eopsechandlerrc amon_cancel_handler(opsecsession *session,amonreqid id); Table 3-49 amon_request_handler session id opsec session id of the request Return Value OPSEC_SESSION_OK OPSEC_SESSION_ERR OPSEC_SESSION_END 74

75 THIRD PARTY TRADEMARKS AND COPYRIGHTS Entrust is a registered trademark of Entrust Technologies, Inc. in the United States and other countries. Entrust s logos and Entrust product and service names are also trademarks of Entrust Technologies, Inc. Entrust Technologies Limited is a wholly owned subsidiary of Entrust Technologies, Inc. FireWall-1 and SecuRemote incorporate certificate management technology from Entrust. Verisign is a trademark of Verisign Inc. The following statements refer to those portions of the software copyrighted by University of Michigan. Portions of the software copyright Regents of the University of Michigan. All rights reserved. Redistribution and use in source and binary forms are permitted provided that this notice is preserved and that due credit is given to the University of Michigan at Ann Arbor. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. This software is provided as is without express or implied warranty. Copyright Sax Software (terminal emulation only). The following statements refer to those portions of the software copyrighted by Carnegie Mellon University. Copyright 1997 by Carnegie Mellon University. All Rights Reserved. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of CMU not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.cmu DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. The following statements refer to those portions of the software copyrighted by The Open Group. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. The following statements refer to those portions of the software copyrighted by The OpenSSL Project. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY * EXPRESSED 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 OpenSSL PROJECT 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. The following statements refer to those portions of the software copyrighted by Eric Young. THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``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 AUTHOR 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. Copyright 1998 The Open Group. 135

76 The following statements refer to those portions of the software copyrighted by Jean-loup Gailly and Mark Adler Copyright (C) Jean-loup Gailly and Mark Adler. This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. The following statements refer to those portions of the software copyrighted by the Gnu Public License. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.you should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The following statements refer to those portions of the software copyrighted by Thai Open Source Software Center Ltd and Clark Cooper Copyright (c) 2001, 2002 Expat maintainers. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. GDChart is free for use in your applications and for chart generation. YOU MAY NOT re-distribute or represent the code as your own. Any re-distributions of the code MUST reference the author, and include any and all original documentation. Copyright. Bruce Verderaime. 1998, 1999, 2000, Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health. Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 by Boutell.Com, Inc. Portions relating to GD2 format copyright 1999, 2000, 2001, 2002 Philip Warner. Portions relating to PNG copyright 1999, 2000, 2001, 2002 Greg Roelofs. Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002 John Ellson ([email protected]). Portions relating to gdft.c copyright 2001, 2002 John Ellson ([email protected]). Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, Doug Becker and copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, Thomas G. Lane. This software is based in part on the work of the Independent JPEG Group. See the file README-JPEG.TXT for more information. Portions relating to WBMP copyright 2000, 2001, 2002 Maurice Szmurlo and Johan Van den Brande. Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation. This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation. This software is provided "AS IS." The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation. Although their code does not appear in gd 2.0.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions. 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 The curl license COPYRIGHT AND PERMISSION NOTICE Copyright (c) , Daniel Stenberg, <[email protected]>.all rights reserved. Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. 136

77 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. The PHP License, version 3.0 Copyright (c) The PHP Group. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is 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. The name "PHP" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. 4. Products derived from this software may not be called "PHP", nor may "PHP" appear in their name, without prior written permission from [email protected]. You may indicate that your software works in conjunction with PHP by saying "Foo for PHP" instead of calling it "PHP Foo" or "phpfoo" 5. The PHP Group may publish revised and/or new versions of the license from time to time. Each version will be given a distinguishing version number. Once covered code has been published under a particular version of the license, you may always continue to use it under the terms of that version. You may also choose to use such covered code under the terms of any subsequent version of the license published by the PHP Group. No one other than the PHP Group has the right to modify the terms applicable to covered code created under this License. 6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes PHP, freely available from < THIS SOFTWARE IS PROVIDED BY THE PHP DEVELOPMENT TEAM ``AS IS'' AND ANY EXPRESSED 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 PHP DEVELOPMENT TEAM 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. This software consists of voluntary contributions made by many individuals on behalf of the PHP Group. The PHP Group can be contacted via at [email protected]. For more information on the PHP Group and the PHP project, please see < This product includes the Zend Engine, freely available at < This product includes software written by Tim Hudson ([email protected]). Copyright (c) 2003, Itai Tzur <[email protected]> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistribution of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Neither the name of Itai Tzur nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission. Chapter 137

78 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 OWNER 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. Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Copyright 2003, 2004 NextHop Technologies, Inc. All rights reserved. Confidential Copyright Notice Except as stated herein, none of the material provided as a part of this document may be copied, reproduced, distrib-uted, republished, downloaded, displayed, posted or transmitted in any form or by any means, including, but not lim-ited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of NextHop Technologies, Inc. Permission is granted to display, copy, distribute and download the materials in this doc-ument for personal, non-commercial use only, provided you do not modify the materials and that you retain all copy-right and other proprietary notices contained in the materials unless otherwise stated. No material contained in this document may be "mirrored" on any server without written permission of NextHop. Any unauthorized use of any material contained in this document may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications regulations and statutes. Permission terminates automatically if any of these terms or condi-tions are breached. Upon termination, any downloaded and printed materials must be immediately destroyed. Trademark Notice The trademarks, service marks, and logos (the "Trademarks") used and displayed in this document are registered and unregistered Trademarks of NextHop in the US and/or other countries. The names of actual companies and products mentioned herein may be Trademarks of their respective owners. Nothing in this document should be construed as granting, by implication, estoppel, or otherwise, any license or right to use any Trademark displayed in the document. The owners aggressively enforce their intellectual property rights to the fullest extent of the law. The Trademarks may not be used in any way, including in advertising or publicity pertaining to distribution of, or access to, materials in this document, including use, without prior, written permission. Use of Trademarks as a "hot" link to any website is prohibited unless establishment of such a link is approved in advance in writing. Any questions concerning the use of these Trademarks should be referred to NextHop at U.S U.S. Government Restricted Rights The material in document is provided with "RESTRICTED RIGHTS." Software and accompanying documentation are provided to the U.S. government ("Government") in a transaction subject to the Federal Acquisition Regulations with Restricted Rights. The Government's rights to use, modify, reproduce, release, perform, display or disclose are restricted by paragraph (b)(3) of the Rights in Noncommercial Computer Software and Noncommercial Computer Soft-ware Documentation clause at DFAR (Jun 1995), and the other restrictions and terms in paragraph (g)(3)(i) of Rights in Data-General clause at FAR , Alternative III (Jun 87) and paragraph (c)(2) of the Commer-cial Computer Software-Restricted Rights clause at FAR (Jun 1987). Use of the material in this document by the Government constitutes acknowledgment of NextHop's proprietary rights in them, or that of the original creator. The Contractor/Licensor is NextHop located at 1911 Landings Drive, Mountain View, California Use, duplication, or disclosure by the Government is subject to restrictions as set forth in applicable laws and regulations. 138

79 Disclaimer Warranty Disclaimer Warranty Disclaimer Warranty Disclaimer Warranty THE MATERIAL IN THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTIES OF ANY KIND EITHER EXPRESS OR IMPLIED. TO THE FULLEST EXTENT POSSIBLE PURSUANT TO THE APPLICABLE LAW, NEXTHOP DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON INFRINGEMENT OR OTHER VIOLATION OF RIGHTS. NEITHER NEXTHOP NOR ANY OTHER PROVIDER OR DEVELOPER OF MATERIAL CONTAINED IN THIS DOCUMENT WARRANTS OR MAKES ANY REPRESEN-TATIONS REGARDING THE USE, VALIDITY, ACCURACY, OR RELIABILITY OF, OR THE RESULTS OF THE USE OF, OR OTHERWISE RESPECTING, THE MATERIAL IN THIS DOCUMENT. Limitation of Liability UNDER NO CIRCUMSTANCES SHALL NEXTHOP BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA OR PROFIT, ARISING OUT OF THE USE, OR THE INABILITY TO USE, THE MATERIAL IN THIS DOCUMENT, EVEN IF NEXTHOP OR A NEXTHOP AUTHORIZED REPRESENTATIVE HAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IF YOUR USE OF MATERIAL FROM THIS DOCUMENT RESULTS IN THE NEED FOR SERVICING, REPAIR OR CORRECTION OF EQUIPMENT OR DATA, YOU ASSUME ANY COSTS THEREOF. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT FULLY APPLY TO YOU. Copyright ComponentOne, LLC All Rights Reserved. BIND: ISC Bind (Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")) Copyright , Theo de Raadt: the OpenBSD 2.9 Release PCRE LICENCE PCRE is a library of functions to support regular expressions whose syntax and semantics are as close as possible to those of the Perl 5 language. Release 5 of PCRE is distributed under the terms of the "BSD" licence, as specified below. The documentation for PCRE, supplied in the "doc" directory, is distributed under the same terms as the software itself. Written by: Philip Hazel <[email protected]> University of Cambridge Computing Service, Cambridge, England. Phone: Copyright (c) University of Cambridge All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * 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. * Neither the name of the University of Cambridge 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 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 OWNER 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. Chapter 139

80 140

81 Index A AMON communication protocol 18 three scope types 18 Amon Scope Types 18 AMON Tables 16 AMON_CANCEL_HANDLER 74 amon_reply_add_oid 66 amon_reply_create 65 amon_reply_destroy 66 amon_reply_get_error 68 amon_reply_get_last_reply_mark 69 amon_reply_get_num_of_oids 67 amon_reply_iter_create 70 amon_reply_iter_destroy 71 amon_reply_iter_next 70 amon_reply_remove_oid 67 amon_reply_send 71 amon_reply_set_error 68 amon_reply_set_last_reply_mark 69 amon_request_get_num_of_oids 62 amon_request_get_scope 62 amon_request_get_size_limit 63 AMON_REQUEST_HANDLER 73 amon_request_iter_create 63 amon_request_iter_destroy 64 amon_request_iter_next 64 AmonReplyIter API 70 s AmonScope_GetAll 63 AmonScope_GetNext 63 AmonScope_GetOne 63 dst_oid 49 err 60, 61, 62 id 72, 73, 74 index 56 iter 64, 65, 70, 71 last_rep_mark 70 LastReply_False 69 B LastReply_True 69 left 52, 53 num_of_elems 54, 55, 56 oid 48, 49, 50, 51, 54, 55, 56, 60, 62, 67 oid_arr 48, 51 oid_arr_length 48, 51 oid_rep 57, 58, 59, 60, 61, 62, 67 oid_str 49 oid1 52 oid2 52 prefix_oid 54 rep 66, 67, 68, 69, 70 reply_err 69 req 62, 63, 64, 72, 73 right 52, 53 session 72, 73, 74 src_oid 49 suffix_oid 55 value 60, 61, 62 blocks 36 D Data Structures 31 E Event Handler Functions 29 Event Handlers 73 AMON_CANCEL_HANDLER 74 AMON_REQUEST_HANDLER 73 F file header 36 Function Calls AmonReply API 65 AmonRequest API 62 AmonRequestIter API 63 Oid API 48 OidRep API 56 Server API 71 I identifier 36 L lexicographic order and containment rules 17 M Multithread 15 reentrant 15 O OID Order and Containment 17 oid_chop_left 55 oid_chop_right 55 oid_compare 51 oid_concat 52 oid_contain 52 oid_create 48 oid_create_from_string 48 oid_destroy 49 oid_duplicate 49 June

82 oid_element 56 oid_get_length 51 oid_prefix 53 oid_reply_create 57 oid_reply_create_with_all 61 oid_reply_destroy 57 oid_reply_get_all 59 oid_reply_get_error 58 oid_reply_get_oid 57 oid_reply_get_opsec_value 58 oid_reply_set_error 61 oid_reply_set_oid 60 oid_reply_set_opsec_value 60 oid_suffix 54 oid_to_array 50 oid_to_string 50 OPSEC OID Tree 21 OPSEC schema mandatory fields 28 OpsecCpmiStatus Schema 27 OpsecCpmiStatusSchema 27 OpsecCvpStatusSchema 24 OpsecElaStatusSchema 26 OpsecLeaStatusSchema 25 OpsecSamStatus Schema 27 OpsecUfpStatusSchema 24 T threads 15 tokens 36 V vendors private schema 36 P porting private schema usage 46 possible values for containment 53 private enterprise number Q Querying Tables 19 S Simple Queries 19 82