The UEM Agent offers the possibility to validate packages before the installation. The validation is done via SHA-256 checksums which are generated per package.
The program CreateHash creates a PackageHashes.json file in the user directory on the Empirum Master Server. The file serves as a checkpoint for the UEM Agent to verify the downloaded package on a client.
Starting with Empirum Version 19.0 the creation of PackageHashes.json files on the Empirum server is automated by a service. This makes the program CreateHash obsolete.
Use of the CreateHash at first use:
- Copy the unpacked directory CreateHash to \Empirum\AddOns\.
- Execute the batch file "Create Hashes for all packages.bat".
- The program parses the SWDepot.dds according to the specified package paths and creates the PackageHashes.json file. The file is stored in the Configurator\User directory.
- The UEM Agent generates a hash value for the package to be installed before installation.
- The UEM Agent checks the generated hash value against the hash value in the PackageHashes.json file to ensure that the package is valid.
- If there are changes in the repository, the batch file "Create Hashes for all unhashed packages.bat" can be executed. The execution of the second batch file updates the PackageHashes.json file.
Enabling package validation for UEM Agent
To activate validation on the client side, set "CheckPackageHash" as DWORD to a value greater than 0 in the registry.
REG ADD HKLM\SOFTWARE\MATRIX42\AGENT /v CheckPackageHash /t REG_DWORD /d 1 /f
Behavior of the UEM Agent:
- If Key CheckPackageHash does not exist, no validation is performed.
- If Key CheckPackageHash exists, the value is set to 0, then no validation.
- If Key CheckPackageHash exists, the value set to 1, then Validation.
If the validation of the packages via hash is activated, the result of the validation can be viewed in the SWDepot log of the EMC under the mode "Validation Status".
Effect of incorrect validation of packets
If the package validation detects a difference between the hash values on the server and on the client, the FailedInstallationRetries counter is incremented for this package. This behavior can be controlled specifically with the CountHashValidationErrors key as DWORD.
- If the key exists and has a value unequal to "1", the counter is not incremented.
- If the key does not exist or has the value "1", the counter is incremented.
Example call for a behavior change:
REG ADD HKLM\SOFTWARE\MATRIX42\AGENT /v CountHashValidationErrors /t REG_DWORD /d 1 /f
Observing the sequence
If, in the order of the UEM Agent package list to be processed, a package has a negative validation, all subsequent packages are no longer executed until the validation is positive.
Enabling package validation via Empirum console
Starting with Empirum version 19.0.0, the validation of packages can be activated via the console. The setting is available under Configuration/Software Management/Empirum Agent/Software Depot in the tab Other settings for the UEM Agent from version 1903.0.
With this option you can activate the check of the packages to be distributed.
The check is performed before the installation by comparing the hash value generated on the server with the hash value generated locally before the installation.