Platform On-PremControl accessAuthenticationAAA

Encrypt passwords

This guide covers password encryption methods for Itential Platform versions 2023.2 and earlier.

The $ENC encryption method is deprecated and will be removed in a future release. Use HashiCorp Vault or CyberArk for new deployments and migrations.

For Platform 6 and later versions, use modern secrets management:

HashiCorp Vault

Automatic property encryption with versioning and audit trails

CyberArk CCP

Enterprise credential provider integration

Legacy $ENC encryption

Use this method only for versions 2023.2 and earlier or during migration periods.

Generate encrypted password

2

Run encryption script

Encrypt your password using npm:

$npm run encrypt mypassword

Output:

Encrypted Password:
$ENC8ef3972b5766e64a98df4b11d6d3221d82812e8caed3459e5a0d
3

Use encrypted value

Copy the entire encrypted string (starting with $ENC) into your configuration.

Example: MongoDB password encryption

1{
2  "mongoProps": {
3    "db": "pronghorn",
4    "url": "mongodb://localhost:27017",
5    "credentials": {
6      "dbAuth": true,
7      "user": "pronghorn",
8      "passwd": "$ENC93eb9439537ae34196db49409dd0261a8b87218fafd0419"
9    }
10  }
11}

Alternative: $SECRET encryption

The $SECRET syntax references secrets stored in HashiCorp Vault.

$SECRET encryption is the replacement for $ENC encryption. It provides better security and integrates with enterprise secrets management.

Secret reference format

$SECRET_<path> $KEY_<key>

Example:

1{
2  "mongoProps": {
3    "credentials": {
4      "dbAuth": true,
5      "user": "pronghorn",
6      "passwd": "$SECRET_database-creds $KEY_mongodb-password"
7    }
8  }
9}

See Manual property encryption for details.

Encrypt properties.json

The properties.json file contains sensitive credentials. Follow best practices for file permissions and encryption.

Set file permissions

1

Restrict file access

Set the file to user-read only:

$sudo chmod 0600 /opt/pronghorn/current/properties.json
2

Verify ownership

Ensure the file is owned by the Itential user:

$sudo chown itential:itential /opt/pronghorn/current/properties.json

Encrypt passwords

2

Encrypt password

$node encrypt.js mypassword

Output:

Encrypted Password: $ENC93eb9439537ae34196db49409dd0261a8b87218fafd0419
3

Update properties.json

Replace the plaintext password with the encrypted string:

1{
2  "mongoProps": {
3    "db": "pronghorn",
4    "url": "mongodb://localhost:27017",
5    "credentials": {
6      "dbAuth": true,
7      "user": "pronghorn",
8      "passwd": "$ENC82ee8a234a69f15bdb8e05409cda2418878b2f85af"
9    }
10  }
11}
4

Restart Platform

Apply the changes:

$sudo systemctl restart itential-platform

Migration from $ENC to Vault

When upgrading to Platform 6, migrate encrypted passwords to HashiCorp Vault.

Migration process

1

Install and configure Vault

Set up HashiCorp Vault integration. See Configure HashiCorp Vault.

2

Create secrets in Vault

Store your plaintext passwords in Vault:

$vault kv put kv-v2/database-creds mongodb-password="mypassword"
3

Update configurations

Replace $ENC references with $SECRET references:

Before:

1{
2  "passwd": "$ENC93eb9439537ae34196db49409dd0261a8b87218fafd0419"
3}

After:

1{
2  "passwd": "$SECRET_database-creds $KEY_mongodb-password"
3}
4

Test configuration

Verify Platform can retrieve secrets from Vault:

$sudo systemctl restart itential-platform
$sudo systemctl status itential-platform
5

Remove $ENC passwords

Once Vault integration is working, remove all $ENC encrypted passwords from your configuration files.

Platform 6 upgrade considerations

When upgrading to Platform 6, all $ENC encrypted secrets must be migrated to HashiCorp Vault or CyberArk. Support for $ENC will be removed in a future release.

Upgrade checklist

  • Install and configure HashiCorp Vault or CyberArk
  • Identify all $ENC encrypted values in your deployment
  • Create corresponding secrets in your vault solution
  • Update configurations to use $SECRET syntax
  • Test all adapters and integrations
  • Verify authentication works correctly
  • Remove $ENC encrypted values from configuration files
  • Document secret locations and naming conventions

See Platform 6 Upgrade: Migration of Encrypted Secrets for detailed upgrade instructions.

Security best practices

File system security

  • Set properties.json to mode 0600 (user read-only)
  • Ensure files are owned by the Itential Platform user
  • Store certificates and keys in protected directories
  • Audit file permissions regularly

Password management

  • Use strong, randomly generated passwords
  • Rotate passwords according to your security policy
  • Never commit encrypted passwords to version control
  • Use vault solutions for centralized secret management

Configuration management

  • Maintain separate configurations for each environment
  • Use environment variables for deployment-specific values
  • Document which passwords are encrypted and where
  • Test password rotation procedures regularly

Troubleshooting

Encrypted password not working:

  • Verify the entire $ENC string is copied (including the prefix)
  • Check for extra spaces or line breaks in the encrypted value
  • Ensure the encryption was generated on the same Platform version
  • Regenerate the encrypted password if corruption is suspected

Migration issues:

  • Verify Vault is properly configured and accessible
  • Check that secret paths and keys match configuration references
  • Ensure Platform has proper permissions to read Vault secrets
  • Review Platform logs for Vault connection errors

Properties.json permission errors:

  • Confirm file permissions are set to 0600
  • Verify file ownership is correct
  • Check that the Itential service user has read access
  • Review SELinux or AppArmor policies if applicable

Next steps

HashiCorp Vault

Migrate to modern secrets management

CyberArk CCP

Enterprise credential provider integration

Rotate AAA passwords

Safely update authentication credentials