OPSEC - Open Platform for Security Remote Access Clients SCV SDK OPSEC - Open Platform for Security Check Point’s OPSEC Open Platform for Security integrates and manages all of network
Trang 115 September 2011
Technical Reference Guide
Remote Access Clients
SCV SDK
E75.20 and higher
Trang 2© 2011 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 252.227-7013 and FAR 52.227-19
TRADEMARKS:
Refer to the Copyright page (http://www.checkpoint.com/copyright.html) for a list of our trademarks
Refer to the Third Party copyright notices (http://www.checkpoint.com/3rd_party_copyright.html) for a list of relevant copyrights and third-party licenses
Trang 3Important Information
Latest Software
We recommend that you install the most recent software release to stay up-to-date with the latest functional improvements, stability fixes, security enhancements and protection against new and evolving attacks
Latest Documentation
The latest version of this document is at:
http://supportcontent.checkpoint.com/documentation_download?ID=12629
For additional technical information, visit the Check Point Support Center
(http://supportcenter.checkpoint.com)
Revision History
Date Description
15 September 2011 First release of this document
Feedback
Check Point is engaged in a continuous effort to improve its documentation
Please help us by sending your comments
(mailto:cp_techpub_feedback@checkpoint.com?subject=Feedback on Remote Access Clients SCV SDK E75.20 and higher Technical Reference Guide)
Trang 4Contents
Important Information 3
Remote Access Clients SCV SDK 5
OPSEC - Open Platform for Security 5
Overview of SCV Checks 5
Programming Model 5
OPSEC SCV Interface 5
Downloading an SCV Policy 6
Enforcing SCV Checks 6
SCV Test Tool 6
SCV API Functions 7
Required Files 7
General APIs 7
Call Back Functions 10
GetScvRegistrationParams 10
Start 11
Stop 11
Init 11
Clean 12
Status 12
GetScvDiagnostics 12
Deploying a Third Party SCV Check 13
How to Create the DLL 13
Edit the SCV Configuration File 14
Integration with Remote Access Clients 16
SCV Check Tool 17
Trang 5
OPSEC - Open Platform for Security
Remote Access Clients SCV SDK
OPSEC - Open Platform for Security
Check Point’s OPSEC (Open Platform for Security) integrates and manages all 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, applications can be configured and managed from a central point, utilizing a single Security Policy editor This document describes the OPSEC SCV ( Secure Configuration Verification) API that you can use to make third party SCV checks to use with Check Point Remote Access clients
Overview of SCV Checks
Secure Configuration Verification (SCV) checks are DLLs (plug-ins) on the client that are invoked and
enforced according to a policy With SCV checks you have:
Reports on the configuration of remote clients
Confirmation that the client complies with the organization's security policy
Blocked connectivity from clients that do not comply
Note - SCV is not supported in SecuRemote
Each check produces a boolean value of compliant or non-compliant that is called by Remote Access
Clients There are multiple SCV checks installed on a computer running Remote Access Clients A single SCV check can test many settings For example: An Anti-Virus SCV check can test if the anti-virus software
is running, has boot sector protection on and has the latest signature files
The SCV check can open a pop up a message to the user and send a log to the Remote Access Clients log file
The client does a checksum check on each of the SCV DLLs If the file has been tampered with, the client is not compliant
Programming Model
This is a detailed description of the usage and integration of SCV checks by Remote Access Clients
Note - For a third party SCV check, the DLL must keep a static data structure if it is
necessary to maintain data during its operation
The SCV Specification has these primary stages:
OPSEC Interface, or the SDK for creating the SCV check DLL
Clients download the SCV policy from the gateway
Enforcement of SCV Checks
OPSEC SCV Interface
The OPSEC SCV interface defines how a third party vendor can write its own SCV checks which will verify the client computer configuration The third party DLL must be installed on each computer that it checks You must also add the new SCV check to the SCV policy that is downloaded from the gateway This tells the Remote Access Clients to enforce the new SCV check
Trang 6SCV Test Tool
Remote Access Clients SCV SDK Page 6
Downloading an SCV Policy
Remote Access Clients downloads policies from the gateway
When the gateway receives a request for a connection that requires SCV compliance, it can query the
connecting client for its SCV status Client computers that report a "compliant" status are allowed to
connect If the client computer is not compliant, the gateway drops the traffic
Enforcing SCV Checks
When the SCV check is in the SCV Policy file the check must also be installed on the client computers If it
is not installed on client computers, Remote Access Clients considers the machine non-compliant, and it will not be permitted to connect to the gateway
The client checks for SCV compliance periodically If an SCV check detects a change in the security
configuration, it reports this change to the Security Management Server and the new SCV status takes effect immediately
SCV Test Tool
The SCV Test Tool lets third party SCV Vendors check their SCV DLL without using a Remote Access
Client
Trang 7SCV API Functions
SCV API Functions
In this section:
This section describes the functions provided by the OPSEC SCV API
Required Files
Header files required for the SCV OPSEC API
File name Description
Scv_Api.h Contains the functions used to communicate with the user and Remote Access
Clients Scv_callback.h Contains the functions that must be implemented by the third party
Scv_error.h Contains the error code conventions
Scv_Internals.h Contains the internal file that must be included in the user implementation
You must statically link these libraries into the SCV DLL to transmit information correctly with Remote
Access Clients
Libraries required for the SCV OPSEC API
Library name Description
PiLib.lib Includes the interface that binds 3rd party code to SCV
Sysprox.lib Includes binding to the Remote Access Clients
Vertlator.lib Includes a version translation mechanism
Register.lib Includes an auto registration mechanism of the SCV PLL into the registry of
Remote Access Clients
General APIs
The general APIs can be used as needed in the SCV DLL
In this section:
Trang 8SCV API Functions
Remote Access Clients SCV SDK Page 8
UserMessageBox
UserMessageBox creates Remote Access Clients message pop-ups for the user
Prototype
SCV_STATUS UserMessageBox (char * lpText,char * lpCaption, unsigned int uType);
Arguments
Argument Meaning
lpText text to appear in the message box
lpCaption message box title
uType window type win32 message box options such as: MB_OK,
etc
Return Values
SCV_STATUS as defined in SCV_error.h
LogScv
LogScv creates a log entry which will be sent to the log server via the Policy Server
Prototype
SCV_STATUS LogScv (char* Origin, char* LogMessage, int Alert);
Arguments
Argument Meaning
Origin SCV check name
LogMessage String with log message
alert If value of alarm is 1, log is of type alert, if value is 0, log is
normal
Return Values
SCV_STATUS as defined in SCV_error.h
UserAllocateString
UserAllocateString tells the SCV DLL allocate a buffer in which to store the SCV name
Note - You can allocate the SCV name buffer GetScvRegistrationParams expects
to receive a pointer to this buffer This API is restricted to the scope of
GetScvRegistryParams do not use it in other scopes
Prototype
SCV_STATUS UserAllocateString (int StringSize, char ** AllocatedPointer)
Arguments
Argument Meaning
StringSize Required buffer size (including the null terminating character)
Trang 9SCV API Functions
Argument Meaning
AllocatedPointer Returned for usage in GetScvRegistrationParams
Return Values
SCV_SUCCESS on success, SCV_ILLEGAL_STRING_SIZE or SCV_ALLOCATION_FAILED on failure
Impersonate User
ImpersonateUser lets the calling thread impersonate the security context of a logged in User
Before you run ImpersonateUser, run IsUserLoggedOn to see if the user is logged in
Prototype
SCV_STATUS ImpersonateUser();
Arguments
None
Return Values
SCV_SUCCESS on success, SCV_FAILED_TO_IMPERSONATE on impersonation failure or
SCV_NOT_IMPLEMENTED if not implemented
RevertSelf
RevertSelf terminates the impersonation of a client application
Prototype
SCV_STATUS RevertSelf();
Arguments
None
Return Values
SCV_SUCCESS on success, SCV_FAILED_TO_REVERT on revert failure or SCV_NOT_IMPLEMENTED if not implemented
IsUserLoggedOn
IsUserLoggedOn lets the calling thread the information to see if user logged on and if the user's GUI is up
Prototype
SCV_STATUS IsUserLoggedOn(BOOL * bIsActive);
Arguments
Argument Meaning
bIsActive Returns TRUE if user logged on Otherwise FALSE
Return Values
SCV_SUCCESS on success, SCV_FAILED_TO_GET_STATE on failing fetch logged on state,
SCV_NOT_IMPLEMENTED if not implemented
Trang 10Call Back Functions
Remote Access Clients SCV SDK Page 10
NotifySCVStatus
NotifySCVStatus is not supported in this version
Return Values
SCV_NOT_IMPLEMENTED
Call Back Functions
Remote Access Clients can call these functions They must all be implemented in the SCV DLL
In this section:
GetScvRegistrationParams
GetScvRegistrationParams is called by the automatic registration mechanism (Pireg.exe) to register or de-register the SCV check into the registry
Prototype
GetScvRegistrationParams (char**vPiName, DWORD*dwMajorVersion, DWORD
*dwMinorVersion, char **vDisplayName, char **vszPrivateData, int install);
Arguments
Argument Meaning
vPiName Returns SCV check name
This is a unique name that represents the SCV DLL, which is enforced by client through SCV policy
dwMajorVersion Returns SCV check major version number
dwMinorVersion Returns SCV check minor version number
vDisplayName Displayed SCV name
vDisplayName contains a short description of the SCV name and functionality to be displayed by the Client Diagnostics Client Diagnostics will be available in future releases
vszPrivateData Private data (usage to be determined)
install 1 to register SCV check, 0 to de-register SCV check
Trang 11Call Back Functions
Return Values
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Note - SCV API.s: UserMessageBox and LogScv should not be called in the above
callback scope
Start
Start is called when the SCV check is started After Start is called the client can query the SCV status Start is called after Init is called
Prototype
SCV_Status Start(int argc, char ** argv);
Arguments
Argument Meaning
argc The number of arguments in argv
argv An array of string arguments in the form argname=argvalue, which are
the parameters provided in the local.scv file for the SCV plugin DLL (see parameters section in local.scv sample) argv[0] is the SCV check name
Return Values
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Stop
Stop is called when the client stops usage of a SCV DLL After Stop is called SCV status is not sent to the client
Prototype
SCV_STATUS Stop ();
Arguments
none
Return Values
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Init
Init is the initialization function for SCV DLLs It can be used for allocation and initialization
Prototype
SCV_Status Init(void *Reserved);
Argument Meaning
Reserved Not Available
Return Values
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Trang 12Call Back Functions
Remote Access Clients SCV SDK Page 12
Clean
Clean is the function that unloads SCV DLLs It can be used for de-allocation
Prototype
SCV_STATUS Clean();
Arguments
None
Return Values
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Status
Status is called by Remote Access Clients when it requires the SCV status (compliant or non-compliant) from the SCV DLL
Prototype
SCV_STATUS Status();
Arguments
None
Return Values
SCV_CHECK_PASSED if the status is compliant or SCV_CHECK_FAILED if the status is non-compliant
GetScvDiagnostics
Remote Access Clients calls GetScvDiagnostics when it requires an SCV rational string, to show secure or insecure configuration from the SCV DLL In every periodic check, the client queries the SCV DLL for status callback and GetScvDiagnostics
Prototype
SCV_STATUS GetScvDiagnostics (char ** ppDiagnostics);
Arguments
Argument Meaning
ppDiagnostics Null terminated string
Note - Copy rational string into ppDiagnostics which is a pre-allocated buffer limited
to 1024 characters
Return Value
Error code SCV_STATUS on success, SCV_GENERAL_FAIL on failure
Trang 13Deploying a Third Party SCV Check
Deploying a Third Party SCV Check
This section describes how to deploy a third party SCV Check in your environment
How to Create the DLL
Create the DLL with MSDEV
Note -
We recommend that you use version Visual C++ 6.0 Service Pack 4 or above
Minimum libraries for compilation on a MSDEV environment using WIN32 is advapi32.lib
To create the SCV DLL:
1 Open an empty MSDEV project (win32 Dynamic-Link-library)
2 Add the required libraries ("Required Files" on page 7) to the project's libraries path
3 Create a new C file or use one of the sample C files provided and include the required header files
("Required Files" on page 7):
#include “Scv_error.h”
#include “Scv_Api.h”
#include “Scv_Internals.h”
#include “Scv_Callback.h”
4 Add all functions defined in Scv_Callback.h (Call Back Functions (on page 10)) You must implement at least a stub, if the function needs no implementation
5 Create a DllMain similar to this:
/*
* DllMain for DLL startup
* This section is necessary for SCV Plugin functionality
*/
BOOL APIENTRY DllMain( HANDLE hModule, DWORD
ul_reason_for_call,
LPVOID lpReserved)
{
/*
* Initialize SCV Plugin with Desktop framework
*/
ContainerInitiator();
switch ( ul_reason_for_call )
{
case DLL_PROCESS_ATTACH:
break;
}
return TRUE;
}
}
6 Make sure to free all memory that is allocated, with the exception of the buffer allocated by
UserAllocateString
7 Compile and build the DLL
8 Debug Use /MDd for debugging or /MD for retail
a) In MSDEV Config Project Settings, enter the C/C++ tab