Custom Script Signing
All custom scripts executed on the local device by the deviceTRUST Agent, or on the remote device by the deviceTRUST Client Extension, must be signed and trusted by the device that they execute on. This impacts the Custom Properties Settings and also the Custom Process Task.
The method used to sign the custom scripts varies by platform.
- Custom Script signing on Microsoft Windows
- Custom Script signing on Linux
- Diagnosing script execution failures
- Custom script signing compatibility
Custom Script signing on Microsoft Windows
Custom Scripts on Microsoft Windows requires a signed and trusted PowerShell script.
Signing a PowerShell Script
Details of how to sign a PowerShell script can be found by running the PowerShell Cmdlet Get-Help about_Signing, or searching Microsoft’s documentation for `about_Signing’.
Trusting the signing certificate
For a signed PowerShell script to be trusted by the Windows device that it executes on, the certificate that was used to sign the script must be present within the Trusted Publishers certificate store. Additionally, if the PowerShell script was signed by a self-signed certificate, the certificate must also be installed within the Trusted Root Certificates certificate store.
Validating the signed script
To validate that a signed PowerShell script can be executed on a device, run the PowerShell Cmdlet Get-AuthenticodeSignature .\my_script.ps1 on that device, where ./my_script.ps1 is the name of your script.
The returned Status field should display the value Valid. If this value is not shown, confirm that the script was successfully signed, has not been modified since it was signed, and that the steps within the previous section have been followed.
Custom Script signing on Linux
Custom Scripts on Linux require a script and a corresponding signature file.
Signing a script
Signing a script for execution on a Linux platform requires access to a certificate in PEM format, and the corresponding private key. To sign the script, run the following command:
openssl cms -sign -in ./my_script.sh -binary -out ./my_script.p7s -signer ./my_certificate.pem -inkey ./my_private.key -outform DER
Note
The script file *./my_script.sh*, certificate *./my_certificate.pem* and private key *./my_private.key* may need to be customised. The signature is saved to file *./my_script.p7s*.
Once signed, the script and signature file can be uploaded into the deviceTRUST® Console.
Trusting the signing certificate
For a script to be trusted by the Linux device that it executes on, the certificate must be added to the trusted store. This can be achieved by copying the certificate to the certificate store and performing an update on the certificate store:
sudo cp ./my_certificate.pem /usr/local/share/ca-certificates/my_certificate.pem
sudo update-ca-certificates
<!--NeedCopy-->
Validating the signed script
The logic for validating that a script has been signed is internal to the deviceTRUST Client Extension for Linux, however the following command should serve as a guide to validating the script has been successfully signed.
openssl cms -verify -in ./my_script.p7s -inform DER -content ./my_script.sh -binary -CAfile ./my_certificate.pem
<!--NeedCopy-->
Diagnosing script execution failures
To better understand failures to execute custom scripts, both on the local or remote device, please refer to the Product Events raised by the deviceTRUST Agent, in particular:
- Event ID 201: Custom Process Executed
- Event ID 202: Custom Process Succeeded
- Event ID 203: Custom Process Failed
Custom script signing compatibility
The requirement for all custom scripts to be signed was introduced in deviceTRUST 2507 and impacts both the deviceTRUST Agent and Client Extension.
The deviceTRUST Agent 2507 and later can send signed PowerShell scripts to the deviceTRUST Client Extension 2503 for Windows or earlier. The scripts must have been signed with a Byte Order Mark (BOM), formatted as UTF-8 and with line separators that include a carriage return and newline.
The deviceTRUST Agent 2507 and later cannot send signed scripts to previous releases of the deviceTRUST Client Extension for Linux. A compatible release will be available soon.
The deviceTRUST Client Extension 2507 for Windows can receive signed custom PowerShell scripts from deviceTRUST Agent 2503 or earlier.
The deviceTRUST Client Extension 2507 for Linux cannot receive signed custom scripts from deviceTRUST Agent 2503 or earlier.