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 ..........................................................................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
 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.

Remote Access Clients SCV SDK Page 5

 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 6

 SCV API Functions

SCV API Functions

In this section:

Required Files 7
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 8
LogScv 8
UserAllocateString 8
Impersonate User 9
RevertSelf 9
IsUserLoggedOn 9
NotifySCVStatus 10

Remote Access Clients SCV SDK Page 7

 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 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)

Remote Access Clients SCV SDK Page 8

 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 9

 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 10
Start 11
Stop 11
Init 11
Clean 12
Status 12
GetScvDiagnostics 12

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

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 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.

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 0.

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:
1. 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.
2. 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:

1. Create a DLL file according to the OPSEC SCV Specifications.
2. Edit the $FWDIR/conf/local.scv file on the Security Management Server to include the third party
check.
3. Install the Desktop Policy on the gateway from the SmartDashboard.
4. 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 <full path of SCV DLL>.
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:
1. Run: net stop tracsrvwrapper from the CLI of the client computer.
2. Download PiReg.exe from www.opsec.com (http://www.opsec.com) to the client computers.
3. On the client computers, run: PiReg.exe -d <full path of SCV DLL>
4. 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:
1. Download the tool from OPSEC.com.
2. Open a Command window, and enter:
<path of tool>\checktool.exe <<path of DLL>\<scv DLL name>>
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
#
1 Init Initialized the Init callback of the SCV DLL

2 Start Starts or Restarts the Start callback of the SCV DLL

3 Get Scv check Status Gets status from the Status callback of the SCV DLL
and query GetScvDiagnostics for SCV rational string

4 Stop Calls the callback that stops the SCV DLL

5 Clean Calls the callback that cleans the SCV DLL

6 Reset Resets the Check Tool to restart checking (can be called

at any point of testing)

7 Init & Start Calls Init and then Start

8 Stop & Clean Calls Stop and then Clean

9 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 do 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:
1. Run Init and then Start.
2. Run Get Scv check Status.
3. Run Stop and Start as necessary.

Remote Access Clients SCV SDK Page 17

 Deploying a Third Party SCV Check

4. Run Clean.
5. 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
do a test of the parameters in the SCV DLL.
To make sure the parameters work correctly:
1. Create a text file called Params.txt and put your parameters in it.
2. Use menu item 10, Set parameters file, to direct the Check Tool to the file path.
3. Use menu item 11, Load params from file, to load the parameters.
4. 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:
1. Open the SCV DLL in MSDEV and change the file type to .All Files*.* to select the DLL.
2. In the debug tab of the project settings, browse and add the checktool.exe as an executable for the
debug session
3. In the same tab, add as Program Arguments <path\scvname>
4. Add breakpoints in your SCV DLL code.
5. Run the Check Tool.

Remote Access Clients SCV SDK Page 18