EncryptedXMLConf Handler

The EncryptedXMLConf handler (ExternalTypes.EncryptedXMLConf) enables CDP properties to store their values in XML configuration files in an encrypted form. This is particularly useful for storing sensitive information such as passwords, API keys, or any confidential data that should not be stored in plain text in the configuration files.

Use Cases:

• For storing passwords and authentication credentials securely
• For protecting API keys and tokens in configuration files
• For any sensitive data that should not be visible in plain text in XML files
• For compliance with security requirements that mandate encryption of sensitive configuration data
• For preventing accidental exposure of secrets in version control or configuration backups

EncryptedXMLConf handler features:

• Values are always stored encrypted in XML configuration files
• Seamless integration with Studio and CDP runtime - values appear decrypted in both offline (in Studio) and in online mode (for Studio and CDP runtime code).
• Seamless re-encryption of values when values are updated, or the encryption key has been changed (and the old key is available)
• Uses AES (Advanced Encryption Standard) encryption
• Support for multiple key sources (built-in, file-based, environment variables)

EncryptedXMLConf handler can be configured using the following properties. The properties can be set per-node using the ExternalType="EncryptedXMLConf;{semicolon-separated list of key=value configuration parameters}" model attribute.

Configuration Properties:

Attaching EncryptedXMLConf to a Property

To attach the EncryptedXMLConf handler to a property, set the ExternalType attribute in a model:

<Attribute Name="Password" Type="string" ExternalType="EncryptedXMLConf"/>

For password fields, it's recommended to also use the Password TypeHint for proper UI presentation:

<Attribute Name="AuthUserPwd" Type="string" ExternalType="EncryptedXMLConf" TypeHint="Password"/>

With custom key configuration:

<Attribute Name="APIKey" Type="string" ExternalType="EncryptedXMLConf;KeyURI=file://secrets.key"/>

or to load key from environment variable named CONF_ENCRYPTION_KEY:

<Attribute Name="APIKey" Type="string" ExternalType="EncryptedXMLConf;KeyURI=env:CONF_ENCRYPTION_KEY"/>

Alternatively, in C++ code, you add the EncryptedXMLConf handler to a node like this:

node->SetExternalType("EncryptedXMLConf");

or

node->SetExternalType("EncryptedXMLConf;KeyURI=env:CONF_ENCRYPTION_KEY");

Built-in Keys vs Custom Keys

Built-in Keys:

CDP provides built-in encryption keys that are automatically used when no KeyURI is specified. These keys:

• Simplify initial setup without requiring key management
• Provide reasonable security for most use cases
• Will change in future versions, while a correct, compatible key is automatically selected based on the CDP version being used.

Custom Keys:

For enhanced security or specific compliance requirements, you can provide custom encryption keys via the KeyURI property:

• File-based keys: KeyURI="file://path/to/keyfile.key" - Reads encryption key from a file
• Environment variables: KeyURI="env:VARNAME" - Reads key from environment variable

Custom keys can be provided in the following formats:

• Raw binary key files (32 bytes for AES-256)
• Hexadecimal encoded strings (64 hex characters)
• Base64 encoded strings (standard base64 encoding)

Encryption Format

Encrypted values are stored in XML using the following format:

KeyURI=<key_identifier>;Nonce=<base64_nonce>;Tag=<base64_tag>;CT=<base64_ciphertext>

Example encrypted value:

KeyURI=bik:1;Nonce=ajQA88+EVocBN5sX;Tag=ToS/w4s6bS+qOTTTASiZRQ==;CT=R/72ANTj9gZWARhzb3A3XxdsNCM9

Where:

• KeyURI - Identifies which key was used for encryption
• Nonce - Cryptographic nonce for AES-GCM
• Tag - Authentication tag for AES-GCM
• CT - Encrypted ciphertext containing the actual value

Runtime Behavior

The EncryptedXMLConf handler provides seamless encryption/decryption:

• At runtime: Values appear decrypted and can be used normally by applications
• In XML files: Values are stored in encrypted format
• In configurator: Values appear decrypted for editing, but are encrypted when saved
• Value changes: Automatically re-encrypted when values are modified
• Key changes: Values are re-encrypted if the KeyURI is changed

Integration with Password TypeHint

EncryptedXMLConf works seamlessly with the Password TypeHint to provide both encryption and UI masking:

<Attribute Name="DatabasePassword" Type="string" ExternalType="EncryptedXMLConf" TypeHint="Password"/>

This combination provides:

• Encryption of the value in XML configuration files
• Password masking (asterisks) in the user interface
• Secure handling throughout the CDP system

Best Practices Using EncryptedXMLConf

When using the EncryptedXMLConf handler, consider the following best practices:

• Use ExternalType="EncryptedXMLConf" for any properties containing sensitive information
• Combine with TypeHint="Password" for password fields to enable UI masking
• For high-security environments, use custom keys via KeyURI instead of built-in keys
• Store custom key files in secure locations with appropriate file permissions
• Use environment variables for keys in containerized or cloud deployments
• Regularly rotate encryption keys and re-encrypt values as needed
• Ensure proper backup and recovery procedures for custom encryption keys
• Test decryption functionality after key changes or system migrations

Configuration Example with File-based Key

For scenarios requiring custom encryption keys, you can specify a key file:

<Attribute Name="SSLPrivateKeyPassword" Type="string" ExternalType="EncryptedXMLConf;KeyURI=file://keys/ssl.key" TypeHint="Password"/>

The key file should contain a 32-byte (256-bit) encryption key in one of these formats:

• Raw binary (32 bytes)
• Hexadecimal (64 hex characters, e.g., "a1b2c3d4e5f6...")
• Base64 (44 characters including padding, e.g., "SGVsbG8gV29ybGQh...")

Configuration Example with Environment Variable Key

For deployment scenarios where keys should be provided via environment variables:

<Attribute Name="CloudAPIKey" Type="string" ExternalType="EncryptedXMLConf;KeyURI=env:CDP_ENCRYPTION_KEY"/>

The environment variable should contain the encryption key in the same formats as file-based keys.

Migration from Plain Text

When adding EncryptedXMLConf to existing properties with plain text values:

• Existing plain text values will be automatically detected
• On first access or value change, plain text will be encrypted
• No manual migration is required
• The encrypted value will be saved to the XML configuration