Obfuscating and Encrypting Passwords

As a system administrator, you define and secure passwords for various components across different sections of the configuration files (INI and application.properties) of the Automation Engine, Java-based Agents, Utilities, Analytics, TLS Gateway, Proxy and Automation.AI.

There are two distinct methods for securing passwords, depending on how your system is configured:

  • Manual Password Obfuscation (Default): The traditional legacy method using the UCYBCRYP utility. This remains the default behavior of the system.

  • Automatic Password Encryption (Opt-in): A newer method built into most configuration files that elevates security from simple obfuscation to true cryptographic encryption. It is disabled by default and must be explicitly enabled via configuration parameters.

    When the feature is enabled, if cleartext passwords or those obfuscated with the UCYBCRYP utility exist in these components, the system automatically updates and rewrites them with the new prefix --20. This means the automatic encryption process replaces any password previously obfuscated manually by the utility.

    Specifically for Utilities, when enabled, the system rewrites passwords in the corresponding INI files when the Java launcher starts. This implies that all *.bat, *.sh, and *.jar files utilize the new automatic encryption, while native binaries (such as ucybdbld.exe and ucybdbld) continue to use the manual obfuscation method.

This page includes the following:

Manual Password Obfuscation

To manually obfuscate your passwords, use the UCYBCRYP utility, that is UCYBCRYP.EXE for Windows and ucybcryp for Linux which are located in the Tools > encrypt folder of your installation directory. Because automatic encryption is an opt-in feature, this manual obfuscation method remains the system default.

Notes:

  • Obfuscating passwords hinders easy disclosure of the values but does not guarantee confidentiality.

  • The password length is limited to 32 characters, with the exception of the CallAPIs for which the lenght is limited to 20 characters.

This method is available for all passwords across your system configuration, for example, the passwords defined in the INI files of the Automation Engine, Utilities, and Agents. However, this utility cannot be used for the Automation.AI component.

You use this manual option as the standard approach whenever the automatic encryption feature is disabled. Additionally, you must use it in specific cases where automatic encryption is not supported or applicable, such as:

  • Non-Java Agents: These agents do not support the new automatic encryption feature, so their passwords must always be manually obfuscated.

  • Zero Downtime Upgrade: Automatic encryption must remain disabled during a ZDU to ensure rollback compatibility and system stability.

Use the following parameters to enter the program via the command line:

Windows:

UCYBCRYP[.EXE] -p -n Password

Linux:

ucybcryp -p -n Password

The PASSWORD.UCC file, which contains the obfuscated password, is created in the same directory. You can copy it to the relevant INI file.

Example

ucybcryp -p -n uc4

Important! An obfuscated password is generated with two leading dashes ( ––10). In Windows, if the content of the PASSWORD.UCC file is output with the command TYPE, two exclamation marks are displayed instead of the leading hyphens; therefore, make sure to copy the password from the file. However, if the obfuscated password is not recognized correctly and you get an error message, try typing in the two leading dashes manually.

Automatic Password Encryption

Automatic password obfuscation is an opt-in feature for securing passwords and keys across different Automic Automation configuration files. It is disabled by default. Once explicitly enabled via your configuration settings, it simplifies and enhances security by automatically encrypting all cleartext credentials at component startup, using a unique, installation-specific key stored in a dedicated security folder. These new encrypted passwords begin with the prefix --20, which distinguishes them from already obfuscated passwords in your configuration files.

Where Automatic Encryption Applies

When enabled, this automatic process applies to the configuration (INI) files of the AE, Utilities, Analytics, TLS Gateway, Proxy, and all Java-based Agents, as well as the application.properties files of Analytics and the Automation.AI component.

When these components start with the feature turned on, any cleartext or obfuscated passwords found in their configuration files are automatically encrypted, and the configuration files are updated accordingly.

While this automatic approach renders the UCYBCRYP utility largely obsolete for components where it is enabled, there are specific circumstances where the utility is still required, see Manual Password Obfuscation.

Enabling Automatic Password Encryption

Because this feature is opt-in, no automatic changes occur anywhere in your system until you explicitly turn it on. To activate automatic encryption, update the relevant parameter in your component's configuration file:

  • For INI files (AE, Utilities, Java-based Agents, Analytics INI, TLS Gateway, Proxy): In the [GLOBAL] section of the relevant INI file, set the write_passwords= parameter to 1 (true). By default, this is set to 0 (false).

    For more information, see Configuration (INI) Files.

  • For Analytics (application.properties): Set the encryption.enabled= parameter to true. By default, this is set to false.

    For more information, see Application Properties File.

  • For LDAP Sync (LDAP Sync.xml): Set the encryption.enabled= parameter to true. By default, this is set to false. For more information, see Configuring LDAP Sync.

  • For Automation.AI (application.properties): Set the automation.ai.encryption.enabled= parameter to true. By default, this is set to false. For more information, see below.

Automatic Password Encryption for Automation.AI

Although the Automation.AI component allows you to use automatic password encryption within its configuration files (application.properties), its underlying logic and mechanism for key management differ from the standard process used by other components.

Note: Because AAKE uses secrets to store credentials, file-based encryption is unnecessary. You can simply leave this feature in its default disabled state (automation.ai.encryption.enabled=false). To use this feature in on-prem environments, you must explicitly turn it on by setting automation.ai.encryption.enabled= to true.

Automation.AI uses a FIPS 140-3 compliant, two-step cryptographic pipeline to secure sensitive properties using a master password, which is stored in the file system at the path defined by the automation.ai.encryption.secret.file property. If the encryption feature is enabled, the application checks for the existence of a master password file at that path:

  • If the file does not exist, the application automatically generates a new, secure 256-bit AES key and creates the file.

  • If the file exists, the key is loaded into memory and used to derive the decryption keys at runtime.

Important! If the master password file is lost, deleted, or modified, previously encrypted values cannot be decrypted. In this scenario, you must restore the master password file from a backup, or reset your properties to plain text and allow the system to re-encrypt them with a newly generated key.

When enabled, the system automatically discovers properties that require encryption across standard Spring Boot configuration locations at startup:

  • Property Identification: The properties to be encrypted are defined using regular expressions in the automation.ai.encryption.candidates parameter, for example, .*\.password,.*\.secret).

  • In-Place Encryption: Cleartext values matching these candidates are encrypted and overwritten directly in the configuration file. The original file formatting, including comments and blank lines, is preserved.

  • The {cipher} Prefix: Encrypted values are prepended with the {cipher} prefix (following the standard Spring Cloud convention). Values that already contain this prefix are skipped during subsequent startups to prevent double encryption.

For more information, see:

Key Management and the Security Folder

Most components share a standard encryption mechanism. During the first startup after the feature is enabled, the system generates a 32-byte encryption key and stores it in a dedicated security folder. If the folder does not exist, the system creates it automatically.

By default, the security folder is located in the bin folder of your installation directory. However, you can customize this location based on the component type:

  • For INI files: Set your preferred path using the securityFolder parameter in the [GLOBAL] section of the INI file.

  • For Analytics (application.properties): Define the key location using the security.folder parameter.

  • For Automation.AI (application.properties): While Automation.AI also performs automatic encryption, it uses a unique logic for key management. Define the specific location of its master password file using the automation.ai.encryption.secret.file parameter.

When you use the Centralized Agent Upgrade (CAU) with this feature enabled, the system automatically applies this encryption method to ensure all your updated components remain secure and consistent.

Note: If you plan to use the same INI file on a different host, make sure to also copy the security folder containing the encryption key along with the configuration (INI) file. Conversely, if you want to share only the INI file without granting access to the passwords, do not share the security folder.

Where Automatic Obfuscation Does Not Apply

Automatic password encryption is not supported or applied in certain scenarios:

  • When Disabled: Since it is disabled by default, no automatic encryption occurs unless explicitly configured. The system will rely on manual obfuscation instead.

  • In Automic Automation Kubernetes Edition: Passwords are managed using secrets, and passwords prefixed with --20 cannot be used in database secrets.

  • Environment Variables: Passwords defined through environment variables are not automatically obfuscated and rewritten.

  • Zero Downtime Upgrade: During ZDU, automatic encryption must remain disabled to ensure rollback compatibility and system stability.

UTF-8: Handling Obfuscated Passwords

The introduction of Unicode support also has an impact on how the system handles new and already obfuscated passwords.

A new password entered in clear text, for example, through PromptSets or while creating a CONN, LOGIN, or USER object, and so on, is obfuscated/encrypted on the fly and stored in the AE database. The clear text password is interpreted as UTF-8 encoded text.

Important! In AWI, input fields that allow you to set a password are restricted to the character encoding allowed in the XML Parameters of the UC_SYSTEM_SETTINGS variable, see XML Parameters.

Obfuscated passwords are generated with two leading dashes, but, in previous versions, they used to have two leading hyphens. To ensure compatibility, the Automic Automation components that process obfuscated passwords can handle both formats.

When an obfuscated password is imported, the system automatically converts it so that it can be handled as UTF-8 encoded.

See also: