Configuring the Service

After installing the HaloENGINE Service, you may want to change the configuration. The Administration Manager tool (hesadm.exe) allows you to configure HaloENGINE Service.

Any changes to labels in the Microsoft Purview portal require restarting the HaloENGINE Service.
If a MPIP label is added, removed, or modified in the Microsoft Purview portal, or if you change the HaloENGINE Service registry settings, the administrator must restart the HaloENGINE Service and HaloENGINE Tomcat service to ensure that the changes take effect. By doing this, labels are updated in HaloENGINE and synchronized with the Microsoft Purview portal.

Administration Manager Tool

The default location for the Administration Manager tool (hesadm.exe) is %ProgramFiles%\Secude\HaloENGINE Service.

hesadm.exe commands

Service Control Commands

hesadm.exe -sc del <service>

Use this command to delete a service.

For example,

hesadm.exe -sc del HES

hesadm.exe -sc list

Use this command to view the service.

Output

For a Domain User

Display Name: Secude HaloENGINE Service
Service Name: HES
Domain: HC.test
User Name: HC.test\administrator
Service Port: 20000
Service Mode: MPIP

Display Name: Secude HaloENGINE Service 1
Service Name: HES1
Domain: HC.test
User Name: HC.test\john
Service Port: 30000
Service Mode: MPIP

For a Non-Domain local user

Display Name: Secude HaloENGINE Service
Service Name: HES
Domain: .
User Name: .\superdocs
Service Port: 20000
Service Mode: MPIP

hesadm.exe -sc start <service>

Use this command to start the HaloENGINE Service. Note: This can be used only after setting user credentials to run HaloENGINE Service.

For example,

hesadm.exe -sc start HES

Output

Service Started successfully.

hesadm.exe -sc stop <service>

Use this command to stop the HaloENGINE Service.

For example,

hesadm.exe -sc stop HES

Output

Service Stopped successfully.

hesadm.exe -log <clean|on|off>

clean: removes all files from the logging directory.
on: enables the service logging.
off: disables the service logging.

For example,

hesadm.exe -log on

Output

Current log enabled, level = 3.

INFO,Log already on.
C:\Users\Administrator\AppData\Local\Secude\HaloENGINE Service\log\

hesadm.exe -log level <1|2|3|4>

Log level: 1: ERROR and INFO
Log level: 2: ERROR, WARNING, and INFO
Log level: 3: ERROR, WARNING, and INFO
Log level: 4: ERROR, WARNING, INFO, and DEBUG

For example,

hesadm.exe -log level 4

Output

Current log enabled, level = 3.

INFO,Logging enabled, level = 4.

hesadm.exe -log purge <days>

Use this command to set a time for log purging, i.e., the no. of day(s) by which the logs will be deleted.

For example,

hesadm.exe -log purge 2

Output

Current log enabled, level = 4.

INFO,Log files purge set to 2 day(s).

hesadm.exe -log rollover <minutes>

Use this command to set a log rollover time, i.e., the minute(s) by which a new log file will be generated.

For example,

hesadm.exe -log rollover 60

Output

Current log enabled, level = 4.

INFO,Log files rollover set to 60 minute(s).

hesadm.exe -enablefips <true|false>

Use this command to enable or disable the FIPS mode.

For example,

hesadm.exe -enablefips true

Output

Enabling FIPS module started.

Service Stopped successfully.

Extracting FIPS module files done.

Trying to Install FIPS modules for this PC.

fips modules configuration generated for this PC successfully.

Service Started successfully.

MPIP Mode Control Commands

Create a New Service

hesadm.exe -sc add <mode (MPIP)> <domain> -user <domain\user> -pwd <password> -port <port_number> <ApplicationID> <Tenant Name> <CertificateStore> ("Current User"|"Local Computer")> <ThumbPrint> <CloudType> [(if Custom) ProtectionCloudURL PolicyCloudURL]

Note:

If no cloud type is mentioned, the "Commercial" cloud type will be considered.
Protection Cloud URL and Policy Cloud URL are only applicable if you choose Custom cloudtype.

This command is used to create a new service.

Prerequisites:

Be sure to use a different user other than an already initialized user.
Be sure to use a port number from the range between 20000 to 65535.
While creating multiple services, make sure to use a different port number other than an already used one.

For example,

For a Domain User

hesadm.exe -sc add MPIP hc.test -user hc.test\john -pwd #9y->\"raQ8< -port 30000 9496505e-f05a-4154-9d66-4f126cedf4b0 halosecude.onmicrosoft.com "Local Computer" 8713f14a4dd8d0c520f79e0416f33c745a3cbeaf https://api.aadrm.com https://dataservice.protection.outlook.com

For a Non-Domain local user:

hesadm.exe -sc add MPIP . -user .\user1 -pwd #9y->\"raQ8< -port 30000 9496505e-f05a-4154-9d66-4f126cedf4b0 halosecude.onmicrosoft.com "LocalComputer" 8713f14a4dd8d0c520f79e0416f33c745a3cbeaf

Output

Service created successfully.

Update MPIP Certificate

hesadm.exe -sc updatempipkeycba <service> <Certificate Store ("Current User"|"Local Computer")> <Certificate Thumbprint> <Tenant Name> <Application ID>

Use this command to update the new MPIP CBA (Certificate-Based Authentication) Keys.

For example,

hesadm.exe -sc updatempipkeycba HES "Current User" 6e9685132e2e86d1b0af75a848fcc7c0ec29839b halosecude.onmicrosoft.com u8352197-65e0-4fd2-9efb-b90027b801fb

Output

MPIP Labels details retrieved successfully.

MPIP key updated successfully.

Display MPIP key

hesadm.exe -sc getvault -user <domain\user> -pwd <password>

Use this command to know your MPIP key information.

For example,

hesadm.exe -sc getvault -user .\administrator -pwd #9y->\"raQ8<

Output
Application ID: u8352197-65e0-4fd2-9efb-b90027b801fb

Tenant Name: halosecude.onmicrosoft.com

Certificate Store: LocalComputer

Certificate Thumbprint: 6e9685132e2e86d1b0af75a848fcc7c0ec29839b

Help Commands

Registry Settings

The following section explains how the registry is used to store service settings. To modify the registry value, open Registry Editor, navigate to this path Registry Root Directory = HKEY_LOCAL_MACHINE\SOFTWARE\Secude\HaloENGINE Service, and modify the Reg Key as you want. Any changes to the registry will require a restart of the HaloENGINE Service to take effect.

Name	Default value	Type	Description
dir_common	`common`	REG_SZ	The path to the directory where all the dependent DLL files are stored for the execution of HaloENGINE Service.
dir_log	`log`	REG_SZ	Log files are generated in the service running the user's local profile i.e. in the following location `%LOCALAPPDATA%\Secude\HaloENGINE Service\log`.
dir_share	`share`	REG_SZ	This folder is for internal use only.
dir_tmp	`tmp`	REG_SZ	It stores the temporary files located at `%LOCALAPPDATA%\Secude\HaloENGINE Service\tmp`.
dir_vendor	`C:\Program Files\Secude\`	REG_SZ	This is the Secude’s vendor directory under which Secude’s components will get installed. For example, HaloENGINE Service.
enable_fips	`false`	REG_SZ	Enable or disable the FIPS mode. true: By selecting this option, MPIP only uses FIPS-compliant encryption algorithms. false: MPIP uses standard encryption algorithms.
log_enable	`on`	REG_SZ	Defines the status of the log. On = Log file will be generated in the default location Off = Log file will not be generated Clean = Log files will be deleted. This parameter deletes only the logs and does not modify the log_enable to "Clean" from "on/off”.
log_level	`3`	REG_SZ	Log level 1: ERROR and INFO Log level 2: ERROR, WARNING, and INFO Log level 3: ERROR, WARNING, and INFO Log level 4: ERROR, WARNING, INFO, and DEBUG
log_purge	`7`	REG_SZ	It indicates removing files older than a defined time frame. By default, the log files older than 7 days will be deleted.
log_rollover	`100`	REG_SZ	Defines the log rollover time, i.e., a new log file will be generated based on the specified minute(s). By default, a new log file will be generated every 100 minutes.
templatefile_purge	`1`	REG_SZ	Defines the purge time of template files that are generated for every CAD assembly file (compound file) download. The default value set is one hour. For example, when a file is downloaded at 15:25 hours, the HaloENGINE Service creates a template file in the tmp\GUID folder (which can be located in the HaloENGINE Service user's profile folder). In the background, it examines and deletes the files which had reached the configured time i.e., after 16:25 hours. Note: This is only applicable in the event of CAD assembly file labeling.
version		REG_SZ	The version number of the installed service.

Configuration in the Registry

Configuring Endpoint

Registry path of endpoint = HKEY_LOCAL_MACHINE\SOFTWARE\Secude\HaloENGINE Service\ep\HES

Name	Default value	Type	Description
block_pii	`false`	REG_SZ	Enable or disable the visibility of Personally Identifiable Information (PII) in the MIP SDK logs. The MIP SDK logs are located at`%LOCALAPPDATA%\Secude\HaloENGINE Service\log\mip_cache_storage\mip\logs\mip_sdk.miplog.` false—PII will be visible in clear text in the MIP SDK logs. true—PII will be masked with asterisks in the MIP SDK logs. This helps to protect the PII's confidentiality.
cachetype	`1`	REG_SZ	MPIP cache storage type used by the service. In Memory—0, maintains the storage cache in memory in the application. On Disk—1 (default storage type), stores the database (SQLite3) on disk in the directory provided in the settings object. The database is stored in plaintext. On Disk Encrypted—2, stores the database (SQLite3) on disk in the directory provided in the settings object. The database is encrypted using OS-specific APIs.
cacheuserlicense	`1`	REG_SZ	0—false, End User License (EUL) will NOT be stored in the MPIP cache storage. 1—true (default value), End User License (EUL) will be stored in the MPIP cache storage.
cloudtype		REG_SZ	User's Azure Cloud Type. For example Commercial.
credential		REG_SZ	Domain or computer name\name of the user under which HaloENGINE Service runs
databoundary	`Default`	REG_SZ	Audit and telemetry events are sent to the nearest collector, where these events are stored and processed. Other options: Asia Europe_MiddleEast_Africa European_Union North_America For example, if your AIP administrator sets North_America, the HaloENGINE Service forces all telemetry and audit data to go directly to North America.
domain		REG_SZ	Name of the domain.
enabledke	`0`	REG_SZ	Double Key Encryption 0 (default value)—Disables the DKE functionality in the HaloENGINE Service. 1 (On)—Enables the DKE functionality in the HaloENGINE Service. Please be aware that DKE labels are only visible when DKE functionality is enabled.
enablefiletracking	`0`	REG_SZ	To register register a protected file to track and revoke. 0 (default value)—the protected file will not be registered for file tracking and access revocation. 1—the protected file will be registered for file tracking and access revocation.
enableminimaltelemetry	`0`	REG_SZ	To transmit diagnostic information to Microsoft. 0 (default value)—all diagnostic events are transmitted. 1—minimum diagnostic events are transmitted.
MIPAuthType	`MSALCBA`	REG_SZ	Type of authentication method (MSALCBA).
mode	`MPIP`	REG_SZ	MPIP
policycloudurl		REG_SZ	Policy Cloud URL. For example: `https://dataservice.protection.outlook.com`
port	`20000`	REG_SZ	Example port that the HaloENGINE Service used to communicate.
protectioncloudurl		REG_SZ	Protection Cloud URL. For example: `https://api.aadrm.com`
service	`HES`	REG_SZ	Name of the service. By default, it is “HES”. If you add more than one service, it will have HES1 and HES2 and so on.
streambuffersize	`10`	REG_SZ	It is a buffer size used for memory-based encryption with the MIP SDK. When the allotted buffer size is exceeded, an additional memory of stream buffer size is allocated, and this process is repeated until the encryption/decryption operation is completed. The default setting is 10MB.

Configuring Endpoint

Proxy Configuration

Many enterprises enforce a Group Policy Objects (GPO) that requires all outbound internet traffic routed through a proxy server. These proxy settings need to be used by both the MIP SDK and the MSAL library for MPIP authentication and functionalities. To use proxy settings for the MSAL library, we need to set the msal_proxy_address in HKEY_LOCAL_MACHINE\SOFTWARE\Secude\HaloENGINE Service.

Name	Type	Data
msal_proxy_address	REG_SZ	`<http://IP Address>`

Configuring MSAL proxy

If the above does not work for service-running users, in such cases, set the registry keys ProxyServer and ProxyEnable in HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings.

Name	Type	Data
ProxyServer	REG_SZ	`<http://IP Address>`
ProxyEnable	REG_SZ	1 to enable. 0 to disable.

Configuring proxy

To allow MIP SDK to use the proxy settings set up in your environment, follow the steps below:

Determine whether the proxy server has been properly set up by running the following command.

C:\Windows\system32>netsh winhttp show proxy

Current WinHTTP proxy settings:

Direct access (no proxy server).

If the response to the command is as shown above, it indicates that the proxy server has not been configured in the registry for winhttp.

To configure the proxy server for winhttp, use the following command:

Syntax: C:\Windows\system32>netsh winhttp set proxy <proxyservername>:<portnumber>

Example: C:\Windows\system32>netsh winhttp set proxy 190.160.166.191:168

In this case, the proxy server that has been set up with 190.160.166.191:168. Once this is executed successfully, the registry gets updated with the proxy server URL and HaloENGINE Service will make sure of the proxy settings.

What to do next?
The next step is to install and configure HaloENGINE after the service has been operational.