Username and Configuration Setting Encryption
uberAgent optionally encrypts user and domain names in the agent and has support to encrypt sensitive settings in its configuration.
User and Domain Names
Encryption
User and domain names can be encrypted in the agent before being sent off to the backend. This can be useful for compliance with privacy regulations.
User and domain name encryption is disabled by default. If required, enable it via the configuration setting EncryptUserNames.
With encryption enabled, user and domain names show up in the backend and in dashboards like this:
Decryption
uberAgent’s download package comes with the command line-tool uAEncrypt.exe, which can be used to decrypt usernames as shown in the following example:
uAEncrypt.exe -decrypt -keyId 101 -data
Configuration Settings
Configuration settings can optionally be obfuscated or retrieved from the OS-specific credential store. Obfuscation is the older option, but less secure. The OS credential store has been added in uberAgent 7.2 and is the recommended way to store passwords and other sensitive information that is required by uberAgent.
Encryption
Some configuration setting may optionally be retrieved from the OS-specific credential store. To indicate to uberAgent that a setting should be read from the OS credential store, specify its value in the following format: ###UA_CREDENTIAL_SOMENAME###. When uberAgent encounters the above format in its configuration, it reads the actual value from the setting SOMENAME in the OS credential store.
Example:
To secure a backend receiver’s REST token, specify it in uberAgent’s configuration as follows:
RESTToken = ###UA_CREDENTIAL_SplunkRESTToken###
Distribute the actual REST token value to the OS credential store (see below) of all endpoints where uberAgent’s configuration references it.
Supported Settings
Encryption is supported for the following configuration settings:
[AzureEventHubsConfiguration]
AzureClientSecret
[CitrixADC_Config]
Password
[CitrixCloud_Config]
ClientSecret
[Receiver]
RESTToken
TLSClientCertificate
Deployment to the OS Credential Store
uberAgent doesn’t handle the deployment of secrets to the endpoint’s OS credential store.
Windows Implementation
uberAgent retrieves credentials from the SYSTEM user’s credential store.
It is essential that the credential is encoded in UTF-8, as uberAgent currently supports only UTF-8 encoded secrets.
Below is a brief example of how to insert a credential into the credential store using PowerShell. It is important that the script is run as NT AUTHORITY\SYSTEM to ensure the secret is added to the SYSTEM user’s credential store.
Script (StoreCredential.ps1):
<#
.SYNOPSIS
Saves credentials to the Windows Credential Manager for uberAgent.
.DESCRIPTION
This script saves credentials (such as a Splunk REST token or other secrets)
to the Windows Credential Manager. The credentials can be retrieved by
uberAgent and used in its configuration.
It must be run as NT AUTHORITY\SYSTEM to store credentials at machine level.
.PARAMETER CredentialName
The name/target under which to save the credential in the Windows Credential Manager.
.PARAMETER SecretValue
The secret value (token, password, etc.) to be stored.
.NOTES
Requirements:
- Run as NT AUTHORITY\SYSTEM to store at machine level
- Add the appropriate configuration attribute to your uberAgent configuration
referencing the credential name with ###UA_CREDENTIAL_CredentialName### syntax
.EXAMPLE
# Run with PsExec to execute as SYSTEM:
# PsExec.exe -s powershell.exe -ExecutionPolicy Bypass -Command "& {"C:\Path\to\Script\StoreCredential.ps1" -CredentialName 'uASplunkRESTToken' -SecretValue (ConvertTo-SecureString 'MySecretToken' -AsPlainText -Force)}"
# Run interactively (will prompt for the secret value):
# PsExec.exe -s -i powershell.exe -ExecutionPolicy Bypass -Command "& {"C:\Path\to\Script\StoreCredential.ps1" -CredentialName 'uASplunkRESTToken' }"
#>
[CmdletBinding()]
param(
[Parameter(Mandatory = $true, HelpMessage = "Name for storing the credential")]
[string]$CredentialName,
[Parameter(Mandatory = $false, HelpMessage = "Secret value to store")]
[SecureString]$SecretValue
)
# Verify the script is running with SYSTEM privileges
$currentProcessSID = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
if ($currentProcessSID -ne "S-1-5-18") {
Write-Error "This script must be run as NT AUTHORITY\SYSTEM. Current process SID: $currentProcessSID"
exit 1
}
# Add required Windows API types for credential management
Add-Type -TypeDefinition @"
using System;
using System.Runtime.InteropServices;
public class CredentialManager {
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct CREDENTIAL {
public uint Flags;
public uint Type;
public string TargetName;
public string Comment;
public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
public uint CredentialBlobSize;
public IntPtr CredentialBlob;
public uint Persist;
public uint AttributeCount;
public IntPtr Attributes;
public string TargetAlias;
public string UserName;
}
[DllImport("Advapi32.dll", SetLastError = true, EntryPoint = "CredWriteW", CharSet = CharSet.Unicode)]
public static extern bool CredWrite([In] ref CREDENTIAL credential, [In] uint flags);
[DllImport("Advapi32.dll", SetLastError = true, EntryPoint = "CredDeleteW", CharSet = CharSet.Unicode)]
public static extern bool CredDelete([In] string targetName, [In] uint type, [In] uint flags);
}
"@
function Set-SecureCredential {
[CmdletBinding()]
param(
[Parameter(Mandatory = $true)]
[string]$Target,
[Parameter(Mandatory = $true)]
[System.Security.SecureString]$SecurePassword
)
# Create a new CREDENTIAL structure
$credential = New-Object CredentialManager+CREDENTIAL
# Configure credential properties
$credential.Flags = 0
$credential.Type = 1 # CRED_TYPE_GENERIC
$credential.TargetName = $Target
$credential.UserName = "" # Empty username
$credential.Persist = 2 # CRED_PERSIST_LOCAL_MACHINE
$credential.Comment = "Created for uberAgent on $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
$BSTR = [IntPtr]::Zero
try {
# First try to delete any existing credential with the same name
# We ignore the result as it doesn't matter if it existed or not
[void][CredentialManager]::CredDelete($Target, 1, 0)
# Convert SecureString to plain text
$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($SecurePassword)
$decodedPassword = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($BSTR)
# Convert to UTF8 bytes
$utf8Bytes = [System.Text.Encoding]::UTF8.GetBytes($decodedPassword)
# Allocate memory and copy the password bytes
$credential.CredentialBlobSize = $utf8Bytes.Length
$credential.CredentialBlob = [System.Runtime.InteropServices.Marshal]::AllocHGlobal($utf8Bytes.Length)
[System.Runtime.InteropServices.Marshal]::Copy($utf8Bytes, 0, $credential.CredentialBlob, $utf8Bytes.Length)
# Write the credential to the Windows Credential Manager
$result = [CredentialManager]::CredWrite([ref]$credential, 0)
if ($result) {
Write-Host "Credential successfully saved for: $Target" -ForegroundColor Green
return $true
}
else {
$errorCode = [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
Write-Error "Error saving credential. Error code: $errorCode"
return $false
}
}
catch {
Write-Error "Exception occurred while saving credential: $_"
return $false
}
finally {
# Securely clear the memory
if ($BSTR -ne [IntPtr]::Zero) {
[System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($BSTR)
}
if ($credential.CredentialBlob -ne [IntPtr]::Zero) {
# Securely zero out the memory before freeing it
[System.Runtime.InteropServices.Marshal]::Copy(
(New-Object byte[] $credential.CredentialBlobSize),
0,
$credential.CredentialBlob,
$credential.CredentialBlobSize
)
[System.Runtime.InteropServices.Marshal]::FreeHGlobal($credential.CredentialBlob)
}
}
}
# Get the secret value from parameter or prompt securely if not provided
if ($null -eq $SecretValue) {
$SecretValue = Read-Host -Prompt "Enter the secret value to store" -AsSecureString
}
# Save credentials to Windows Credential Manager
$result = Set-SecureCredential -Target $CredentialName -SecurePassword $SecretValue
# Print configuration instructions if successful
if ($result) {
Write-Host ""
Write-Host "uberAgent Configuration Instructions:" -ForegroundColor Cyan
Write-Host "------------------------"
Write-Host "Add the following to your uberAgent configuration file:"
Write-Host ""
Write-Host " AttributeName = ###UA_CREDENTIAL_$CredentialName###" -ForegroundColor Yellow
Write-Host ""
Write-Host "Where 'AttributeName' could be any configuration attribute that requires a credential,"
Write-Host "such as 'RESTToken' in the [Receiver] stanza for Splunk authentication."
Write-Host ""
Write-Host "For more information, see the uberAgent documentation on credential storage:"
Write-Host ""
Write-Host "https://docs.citrix.com/en-us/uberagent/current-release/uxm-features-configuration/username-and-configuration-setting-encryption-2.html" -ForegroundColor Cyan
Write-Host ""
}
Examples:
Secret provided via CLI.
# Run with PsExec to execute as SYSTEM:
# Replace "C:\Path\to\Script\" with the actual script path
# Replace 'MySecretToken' with your secret
PsExec.exe -s powershell.exe -ExecutionPolicy Bypass -Command "& {"C:\Path\to\Script\StoreCredential.ps1" -CredentialName 'uASplunkRESTToken' -SecretValue (ConvertTo-SecureString 'MySecretToken' -AsPlainText -Force)}"
Secret will be prompted interactively.
# Run interactively (will prompt for the secret value):
# Replace "C:\Path\to\Script\" with the actual script path
PsExec.exe -s -i powershell.exe -ExecutionPolicy Bypass -Command "& {"C:\Path\to\Script\StoreCredential.ps1" -CredentialName 'uASplunkRESTToken' }"
Verification:
To verify that the secret was added, run the following command:
PsExec.exe -s -i rundll32.exe keymgr.dll,KRShowKeyMgr
The dialog should display the name of the secret that was just added.
macOS Implementation
Under macOS the credentials are read from the keychain (more information). The keychain items
must be stored in the system keychain, and uberAgent must be exempt from the option Confirm before allowing access under the tab Access Control.
Example:
To create a keychain item securing the REST token for Splunk, you can run the following command line:
sudo security add-generic-password -a "Splunk" -s "uberAgent" -w "TOKEN_TO_BE_USED" -T "/Library/uberAgent/uberAgent.app" -U /Library/Keychains/System.keychain
where Splunk is the keychain item’s account name, uberAgent is the service name and TOKEN_TO_BE_USED the REST token. The account name can be chosen freely. If you want to change the default service name uberAgent, you can do so by adding the configuration option CredentialStoreServiceName in stanza Miscellaneous, and passing the name with option -s as seen in the example above.
Example:
[Miscellaneous]
ConfigFlags = CredentialStoreServiceName:MY_CUSTOM_SERVICE_NAME
Obfuscation
Sensitive settings like passwords can be obfuscated with the command-line tool uAEncrypt.exe, which is available in the uberAgent download package. The syntax is viewable by running uAEncrypt.exe -?.
To encrypt MySecretPassword:
uAEncrypt.exe -encrypt -keyId 1 -data PlaintextData
De-Obfuscation
De-obfuscation is possible with:
uAEncrypt.exe -decrypt -keyId 1 -data ObfuscatedData
Supported Settings
Obfuscation is supported for all configuration settings.