Remote Access Clients SCV SDK E75.20 and higher Technical Reference Guide 15 September 2011 © 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 Important 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) Contents Important Information .3 Remote Access Clients SCV SDK OPSEC - Open Platform for Security Overview of SCV Checks Programming Model OPSEC SCV Interface Downloading an SCV Policy Enforcing SCV Checks SCV Test Tool SCV API Functions Required Files General APIs 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 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 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 Remote Access Clients SCV SDK Page SCV Test Tool 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 Remote Access Clients SCV SDK Page SCV API Functions SCV API Functions In this section: Required Files General APIs 7 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: UserMessageBox LogScv UserAllocateString Impersonate User RevertSelf IsUserLoggedOn NotifySCVStatus 8 9 10 Remote Access Clients SCV SDK Page SCV API Functions 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 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) Remote Access Clients SCV SDK Page SCV 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 Remote Access Clients SCV SDK Page Call Back Functions 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 Start Stop Init Clean Status GetScvDiagnostics 10 11 11 11 12 12 12 GetScvRegistrationParams GetScvRegistrationParams is called by the automatic registration mechanism (Pireg.exe) to register or deregister 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 to register SCV check, to de-register SCV check Remote Access Clients SCV SDK Page 10 Call 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 Remote Access Clients SCV SDK Page 11 Call Back Functions 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 Remote Access Clients SCV SDK Page 12 Deploying 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 or above Minimum libraries for compilation on a MSDEV environment using WIN32 is advapi32.lib To create the SCV DLL: Open an empty MSDEV project (win32 Dynamic-Link-library) Add the required libraries ("Required Files" on page 7) to the project's libraries path 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 #include #include #include “Scv_error.h” “Scv_Api.h” “Scv_Internals.h” “Scv_Callback.h” 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 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; } } Make sure to free all memory that is allocated, with the exception of the buffer allocated by UserAllocateString Compile and build the DLL Debug Use /MDd for debugging or /MD for retail a) In MSDEV Config Project Settings, enter the C/C++ tab Remote Access Clients SCV SDK Page 13 Deploying a Third Party SCV Check b) On the Code Generation Category choose run time library c) Choose Debug Multithreaded DLL (for debugging) or Multithreaded DLL for retail Edit the SCV Configuration File Integrate the third party check into the local.scv configuration file Define the check in the SCVNames section Like all SCV checks, it can have parameters Add the name of the check under SCVPolicy This tells the client to run the check For more about SCV policy syntax, see the Remote Access Clients Administration Guide for version E75.20 or higher The name of the check that you use in the configuration file is the name that you defined for vPiName in the GetScvRegistrationParams function in the DLL After you update the file, Install Desktop Policy on the gateway This example shows part of a local.scv file with a third party SCV check added In the example, it has one parameter, Checkfile, with the value Remote Access Clients SCV SDK Page 14 Deploying a Third Party SCV Check (SCVObject :SCVNames ( : (3rdPartyScv :type (plugin) :parameters ( :CheckFile (0) ) ) : (SCVMonitor :type (plugin) :parameters ( :scv_version (54014) :begin_admin (admin) :send_log (alert) :mismatchmessage ("Please upgrade your Secure Configuration Verification products package") :end (admin) ) ) : (sc_ver_scv :type (plugin) :parameters ( :Default_SecureClientBuildNumber (52032) :Default_EnforceBuildOperand ("==") :MismatchMessage ("Please upgrade your SecureClient.") :EnforceBuild_9X_Operand (">=") :SecureClient_9X_BuildNumber (52030) :EnforceBuild_NT_Operand ("==") :SecureClient_NT_BuildNumber (52032) :EnforceBuild_2K_Operand (">=") :SecureClient_2K_BuildNumber (52032) :EnforceBuild_XP_Operand (">=") :SecureClient_XP_BuildNumber (52032) ) ) : (ckp_scv :type (plugin) :parameters ( :protect_all_ifc (true) :non_ip_protocols (true) :send_log (true) :send_warning (true) ) ) ) :SCVPolicy ( : (SCVMonitor) : (3rdPartyScv) ) :SCVEpsPolicy ( : (WindowsSecurityMonitor) ) … :SCVGlobalParams ( :enable_status_notifications (false) :status_notifications_timeout (10) :disconnect_when_not_verified (false) :block_connections_on_unverified (false) :scv_policy_timeout_hours (168) :enforce_ip_forwarding (false) :not_verified_script () Remote Access Clients SCV SDK Page 15 Deploying a Third Party SCV Check :not_verified_script_run_show (false) :not_verified_script_run_admin (false) :not_verified_script_run_always (false) :allow_non_scv_clients (false) :skip_firewall_enforcment_check (true) ) ) ) Integration with Remote Access Clients Each client computer must have the DLL file, preferably in the same directory as the installation file You can deploy the Third Party DLL file in two ways: We recommended that you add the DLL to an MSI package with the Check Point MSI Packaging tool utility When clients install the MSI they automatically get the DLL For more about the Check Point MSI Packaging tool utility, see the Remote Access Clients Administration Guide for version E75.20 or higher To add the check to an existing installation, you must manually distribute the DLL and manually run the PiReg.exe tool Get this from www.opsec.com (http://www.opsec.com) > Remote Access Clients SCV SDK Note - If you add the check to an existing installation on Windows 7, you must run the PiReg command with administrator permissions Right-click the cmd.exe program and select Run as Administrator When the command line opens, run the correct PiReg command To activate a third party SCV check: Create a DLL file according to the OPSEC SCV Specifications Edit the $FWDIR/conf/local.scv file on the Security Management Server to include the third party check Install the Desktop Policy on the gateway from the SmartDashboard Distribute the SCV DLL file to each client computer in one of these ways: To add a third party SCV file to an MSI package: Use the Check Point MSI Packaging tool commands to edit the MSI package and add, remove, and overwrite a third party plug-in file To add a third party SCV file to an existing Remote Access Clients installation: a) Distribute the DLL to all client computers b) Run: net stop tracsrvwrapper from the CLI of the client computers c) Download PiReg.exe from www.opsec.com (http://www.opsec.com) to the client computers d) On the client computers, run: PiReg.exe e) Run: net start tracsrvwrapper from the CLI of the client computers When a client tries to connect to the VPN gateway, the third party SCV check operates with the other SCV checks If it is necessary to replace the DLL file, first unregister the current file This makes the file inactive To unregister a third party check on a client computer: Run: net stop tracsrvwrapper from the CLI of the client computer Download PiReg.exe from www.opsec.com (http://www.opsec.com) to the client computers On the client computers, run: PiReg.exe -d Run: net start tracsrvwrapper from the CLI of the client computer Remote Access Clients SCV SDK Page 16 Deploying a Third Party SCV Check SCV Check Tool The SCV Check Tool is a command line testing tool that is part of the SCV OPSEC SDK It is implemented in checktool.exe Third parties can use this tool to run or debug SCV DLLs without a Remote Access Client Using the Check Tool To use the Check Tool: Download the tool from OPSEC.com Open a Command window, and enter: \checktool.exe For example D:\Temp\checktool.exe C:\samplescv.dll When the Check Tool starts, the main menu opens From the main menu, enter a number to run an API callback function Below is a summary of the functions available See Call Back Functions (on page 10) for a full description of each function Menu Command Name # Description Init Initialized the Init callback of the SCV DLL Start Starts or Restarts the Start callback of the SCV DLL Get Scv check Status Gets status from the Status callback of the SCV DLL and query GetScvDiagnostics for SCV rational string Stop Calls the callback that stops the SCV DLL Clean Calls the callback that cleans the SCV DLL Reset Resets the Check Tool to restart checking (can be called at any point of testing) Init & Start Calls Init and then Start Stop & Clean Calls Stop and then Clean Operate Scv under robust scenario Runs a simulation that tests a realistic scenario Call this after Clean or Reset or before Init 10 Set Parameters file path Direct the Check Tool to the directory of your params.txt file 11 Load params from file Initiate loading of params from the params.txt file 100 Exit Leave the application Sequence for Running Check Tool When you run the test tool, work in a logical sequence If you not work in a logical sequence, you get an error and the command does not run After an error, you can continue from the same point Here is a suggested logical work sequence: Run Init and then Start Run Get Scv check Status Run Stop and Start as necessary Remote Access Clients SCV SDK Page 17 Deploying a Third Party SCV Check Run Clean Repeat all of the above as necessary Checking Parameters If the SCV DLL uses parameters, for example, the argc and argv parameters of the Start callback, you can a test of the parameters in the SCV DLL To make sure the parameters work correctly: Create a text file called Params.txt and put your parameters in it Use menu item 10, Set parameters file, to direct the Check Tool to the file path Use menu item 11, Load params from file, to load the parameters The next time you call menu item 2, Get Scv check status, the parameters will pass to the SCV DLL Format of Params.txt file Use this format for the contents of the file: Scvname Param1=value1 Param2=value2 Example: samplescv n1param1=value1 n1param2=value2 n1param3=value3 Debugging the SCV DLL We recommended that you create an MSDEV project for the DLL and run it step-by-step while you use the Check Tool To create a debugging environment in MSDEV: Open the SCV DLL in MSDEV and change the file type to All Files*.* to select the DLL In the debug tab of the project settings, browse and add the checktool.exe as an executable for the debug session In the same tab, add as Program Arguments Add breakpoints in your SCV DLL code Run the Check Tool Remote Access Clients SCV SDK Page 18 ... immediately SCV Test Tool The SCV Test Tool lets third party SCV Vendors check their SCV DLL without using a Remote Access Client Remote Access Clients SCV SDK Page SCV API Functions SCV API Functions... 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 Remote Access Clients SCV SDK Page SCV Test Tool... (mailto:cp_techpub_feedback@checkpoint.com?subject=Feedback on Remote Access Clients SCV SDK E75.20 and higher Technical Reference Guide) Contents Important Information .3 Remote Access Clients SCV SDK OPSEC -