Device Control Client Side SDK API

Ivanti Device and Application Control (IDAC) enables IT administrators to control users' access to devices, preventing accidental data loss, data theft or the leak of confidential information. Account and device based policies, controlled from a central system, enable you to apply powerful security measures that act as a prevention rather than a cure.

This API and its accompanying SDK enable third party integrators to access these powerful features for use in their own products.

Many of the commands in this SDK begin with HSDC, which was the abbreviation used internally for the product when its development began.

Usage Considerations

  • On an existing installation that uses both Server and Agent components, you can use the Agent SDK deployed by the standard installation to access inventory, perform access checks, control encryption, and so on. This could be for support purposes, but also to perform some compliance checks, control some actions from an automation engine or provide an alternative user interface.
  • On a serverless environment, either by using the agent MSI installer or the packages below, an agent can be given policies, logs and shadow files can be consumed and sent to a SIEM/3rd party storage.

An RSA keypair is needed to control the agents and it is the responsibility of the integrator to secure the private key, preferably on server-side.

Packages

The Ivanti Device Control Software Development Kit comprises the following main packages:

Quick Start Guide

  1. Download the Core Package to a Virtual Machine and unzip it to, for example, .
  2. Download the Agent Package to the same machine, unzip it and run:
    Set-ExecutionPolicy Bypass; ./sdk-agent-deploy.ps1 -EnableTestSigning -Verbose

    Test signing is required only if you are running a machine with UEFI Secure Boot enabled and you are using a development version of the SDK (as opposed to a GA version). As an alternative to bypassing the execution policy you can also disable it using Set-ExecutionPolicy Unrestricted. The -Verbose parameter is used to highlight what is happening, but is not necessary.

  3. Let the machine restart.

Verification

After the agent installation script runs (presuming you use it) you should have three new running services:

  • scomc: The user-mode client service
  • sk: The kernel mode driver
  • skfs: The kernel mode file-system driver

Query the statuses of the services using the sc query {service name} command via cmd.exe. This needs to be run as administrator.

Controlling logging

Logging is disabled by default but can be controlled by the registry for each component, allowing outputs on console, file, or for debug view.

Here is a registry file example that can be merged:

Copy 
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\scomc\parameters]
"Log to console"="yes"
"Log to file"="yes"
"Log to dbwin"="no"
"Log file name"="c:\\temp\\scomc.log"
[HKEY_LOCAL_MACHINE\SOFTWARE\Lumension Security\RTNotify]
"Log to console"="no"
"Log to file"="yes"
"Log to dbwin"="no"
"Log file name"="c:\\temp\\rtnotify.log"
[HKEY_LOCAL_MACHINE\SOFTWARE\Lumension Security\dcext]
"Log to console"="no"
"Log to file"="yes"
"Log to dbwin"="no"
"Log file name"="c:\\temp\\dcext.log"
[HKEY_LOCAL_MACHINE\SOFTWARE\Lumension Security\dcextExplorer]
"Log to console"="no"
"Log to file"="yes"
"Log to dbwin"="no"
"Log file name"="c:\\temp\\dcextExplorer.log"

Next Steps

When the agent is installed you can use the items below to get a feel for the way the policies work. By default the agent has a log under C:\Temp\scomc.log. The log file does not include logging internal to the DC API component, just the runtime, but if the return code from the API is not giving you enough information this is the first place to look.

Use RunDll32.exe/HSDC32Cmd.exe/HSDC64Cmd.exe to import your first policy

Get started by trying out the RunDll32 compatible Command function. It has a lot of commands available that you can query using the Help command (rundll32 HSDC32.dll,Command -Help or HSDC32Cmd.exe -Help or HSDC64Cmd.exe -Help). To use it you need a license that will be provided to each call.

The core functionality of the DC SDK is focused around the ability to import and apply polices for controlling access to devices. To do this you need:

  • The agent runtime installed (run the PowerShell script following the instructions above; a reboot is required).
  • A JSON policy file. See the example Policy Default Settings as a good starting point. Copy it and save it as default.json in the lib folder of the agent core package.
  • A public-private RSA key-pair for signing your policies (indicating that the origin of the policy is trusted).

To import your first policy:

  1. After the runtime is installed, try to access a USB device and notice that you are blocked. The default.json policy will allow access once again.
  2. To generate a public-private key pair run the following command:
    HSDC64Cmd.exe -License endpoint.lic -GenKeyPair rsa2048

    3. This is for a 64-bit system. If you are using a different machine flavor, use the corresponding executable.

    The generated key-pair will be rsa2048-pub.key and rsa2048-priv.key next to the HSDC DLL.

  3. Rename the keys to sx-public.key and sx-private.key respectively.
  4. Copy the sx-public.key file to the agent's SXDATA folder.
    The SXDATA folder is in SystemRoot%, for example C:\Windows\.
  5. Finally, restart the agent's scomc service (if it fails to stop you can kill the process safely) and you are ready to import a signed policy into the agent:
    HSDC64Cmd.exe -License endpoint.lic -RSAPrivateKey sx-private.key -RSAPublicKey sx-public.key -SignImportJsonPolicy default.json

    6. You can now access your USB (and other) devices.

This is meant to verify the good health of the deployment, as the private key shouldn't be on the agent for a normal usage or secured by a third party component.

API Docs

Hand-in-hand with the sample client is the API documentation found under Modules, which specifies the various functions and their uses. A casual glance at this will provide an overview of the capabilities that are available through Ivanti Application and Device Control. The API docs also provide example JSON for parameters in most cases.

Examples

The Code Examples page gives you a head-start in implementing your own code.

Installation Guide

PowerShell Script

To install a development environment:

  1. Unpack the core zip-file to a convenient location on your development machine. For a C/C++ application, link to the HSDC32/64.lib and include the SDK header file HSDC_Sdk.h in your code.
  2. Unzip the agent package to a convenient location on your test machine and run the sdk-deploy-agent.ps1 PowerShell script.
    The script documentation provides examples and descriptions of possible parameters. Note that most API calls require that these runtime components are available. If you are deploying a non-release version of the API then you enable test signing using the parameter on the deployment script (do this on a disposable environment).
  3. Unpack the zip file to a convenient location on your test machine and use the provided sdk-deploy-uitools.ps1 PowerShell script.
    The script's documentation explains the operations in more detail. Before using the RTNotify status window you must have imported at least one policy on the agent.

The PowerShell scripts are designed for use in development environments by technically proficient users. They may be used by application developers as a starting point for their own deployment tools if they do not wish to repackage the official installer. The use of the PowerShell scripts requires the installation of PowerShell 4.0. In turn this requires the .NET Framework 4.0 or later. We highly recommend that you install the latest PowerShell (Window Management Framework) and .NET Framework available for your system.

The PowerShell deployment script for the runtime components can also be used to uninstall the runtime components. It will detect if you have installed the components already and, if so, it will uninstall them.

Silent MSI from Ivanti DAC Agent

A silent installation of the Ivanti DAC Agent is described on the Ivanti Community.
For a clean installation, a valid .dat file should be provided or alternatively a valid dc .lic file.

Custom Scripts

As the scripts above require the use of PowerShell 4.0 or later, some platforms are not supported (see Microsoft's documentation for WMF). Developers who need to install their test environment on another platform may use the ES Client MSI, which installs the required runtime. Alternatively, the steps of the installation can be followed via the source of the PowerShell scripts and re-implemented in other scripting platforms if required.

A Manual Steps installation results in a “hidden” installation with no license. Policy may be delivered during installation by setting a policy file in the Import folder. Also, an RSA key pair is used to secure the communication with the agent and API. The public key must be exported in a file encoded in PKCS#8 (PKCS#1 is also supported for legacy).