Encryption and Data Security

This document covers Maho's encryption and data security infrastructure, including the encryption model, key management, password hashing, and secure storage of sensitive configuration data. For broader security topics including authentication, ACL, and session management, see the Security and Authentication section.

Purpose and Scope

This page documents:

• The encryption architecture and core APIs (Mage_Core_Model_Encryption, helper methods)
• Encryption key storage, format, and rotation procedures
• Password hashing mechanisms and character sets
• Which data fields are encrypted in the database (Vault, Config, Payments, Feed Manager)
• The encryption key regeneration process and migration from Magento 1

Encryption Architecture

Maho uses the modern PHP Sodium extension for encryption, with backward compatibility for legacy Magento 1 encryption keys.

Encryption Components Diagram

Sources:

• app/code/core/Mage/Core/Helper/Data.php23-78
• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php57-115
• app/code/core/Maho/FeedManager/Model/Destination.php70-72

Core Encryption APIs

Helper Methods

The primary encryption interface is through Mage_Core_Helper_Data. It manages the lifecycle of the encryptor object and provides shorthand methods for common operations.

Method	Description	Returns
encrypt(string $data)	Encrypts plaintext data using application key	string
decrypt(?string $data)	Decrypts ciphertext using application key	string
encryptIdempotent($data)	Encrypts data only if it is not already encrypted	string
tryDecrypt($data)	Attempts to decrypt; returns null on failure	string|null
getEncryptor()	Returns singleton encryption model instance	Mage_Core_Model_Encryption

The encryption helper lazily initializes the encryption model, configurable via the XML path global/helpers/core/encryption_model app/code/core/Mage/Core/Helper/Data.php23 By default, it uses Mage_Core_Model_Encryption app/code/core/Mage/Core/Helper/Data.php72

Sources:

• app/code/core/Mage/Core/Helper/Data.php51-78

Encryption Model

Mage_Core_Model_Encryption provides the underlying encryption implementation. It is designed to handle:

• Modern encryption: Sodium-based encryption with SODIUM_CRYPTO_SECRETBOX_KEYBYTES (32 bytes).
• Legacy support: Optional compatibility for Magento 1 keys during migration lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php64-72
• Key validation: Ensures keys meet format requirements during regeneration.

Sources:

• app/code/core/Mage/Core/Helper/Data.php65-78
• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php57-58

Encryption Key Management

Storage Format

The encryption key is stored in app/etc/local.xml within the <global><crypt><key> node. During regeneration, Maho adds a date attribute to track when the key was rotated lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php59-61

• Format: Hexadecimal string.
• Length: 64 characters for modern keys (representing 32 bytes) lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php64
• CDATA wrapper: Used to ensure the hex string is treated as literal data.

Key Access Methods

Method	Description	Location
Mage::getEncryptionKeyAsHex()	Retrieves current key from local.xml	Mage class
Mage::generateEncryptionKeyAsHex()	Generates new random 32-byte key	Mage class

Sources:

• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php57-58

Password Hashing

Maho supports multiple password hashing algorithms. The system defines various character sets for password and salt generation, including specific sets for lowers, uppers, digits, and special characters app/code/core/Mage/Core/Helper/Data.php27-34

Character Set Definitions

Maho categorizes characters to ensure password complexity:

• CHARS_PASSWORD_LOWERS: abcdefghjkmnpqrstuvwxyz app/code/core/Mage/Core/Helper/Data.php31
• CHARS_PASSWORD_SPECIALS: !$*-.=?@_ app/code/core/Mage/Core/Helper/Data.php34

Sources:

• app/code/core/Mage/Core/Helper/Data.php27-34

Encrypted Data Storage

Several database tables store sensitive information that is encrypted at rest using Mage_Core_Helper_Data.

Core Encrypted Fields

Table	Field	Content
core_config_data	value	Sensitive configuration (API keys, SMTP passwords).
sales_flat_quote	password_hash	Customer password hashes in quotes app/code/core/Mage/Checkout/Model/Observer.php58
sales_flat_quote_payment	cc_number_enc, cc_cid_enc	Encrypted credit card details app/code/core/Mage/Payment/Model/Observer.php178
maho_paypal_vault_token	paypal_token_id	PayPal Vault tokens app/code/core/Maho/Paypal/Model/Resource/Vault/Token.php29
feedmanager_destination	config	Credentials for external feed destinations app/code/core/Maho/FeedManager/Model/Destination.php70-72
admin_activity_log	details	Encrypted audit trail details app/code/core/Maho/AdminActivityLog/Model/Activity.php23

PayPal Vault Token Hashing

For the PayPal Vault system, Maho uses a dual approach:

1. Encryption: The paypal_token_id is encrypted for storage app/code/core/Maho/Paypal/Model/Resource/Vault/Token.php29
2. Hashing: A SHA-256 hash of the plaintext token is stored in paypal_token_id_hash to allow for efficient lookups without decrypting all records app/code/core/Maho/Paypal/Model/Resource/Vault/Token.php28

Sources:

• app/code/core/Mage/Checkout/Model/Observer.php46-64
• app/code/core/Mage/Payment/Model/Observer.php166-185
• app/code/core/Maho/Paypal/Model/Resource/Vault/Token.php22-48
• app/code/core/Maho/FeedManager/Model/Destination.php63-82

Encryption Key Regeneration

The CLI command sys:encryptionkey:regenerate (MahoCLI\Commands\SysEncryptionKeyRegenerate) handles the rotation of the application encryption key. This process includes automated re-encryption of data across various tables.

Regeneration Workflow

Sources:

• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php126-132
• app/code/core/Mage/Payment/Model/Observer.php166-185
• app/code/core/Maho/FeedManager/Model/Observer.php18-36

Event-Driven Re-encryption

When the key is regenerated, the command dispatches the encryption_key_regenerated event lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php126-130 This allows core and third-party modules to re-encrypt their specific data using provided callbacks:

• Mage_Payment: Re-encrypts sales_flat_quote_payment using Mage_Core_Helper_Data::recryptTable app/code/core/Mage/Payment/Model/Observer.php166-185
• Mage_Checkout: Re-encrypts sales_flat_quote password hashes app/code/core/Mage/Checkout/Model/Observer.php46-64
• Maho_FeedManager: Re-encrypts feedmanager/destination table app/code/core/Maho/FeedManager/Model/Observer.php18-36

Sources:

• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php126-132
• app/code/core/Mage/Payment/Model/Observer.php166-185
• app/code/core/Maho/FeedManager/Model/Observer.php18-36

Migration from Magento 1

Maho provides a path for migrating from Magento 1 (M1) encryption keys.

1. Detection: The system identifies M1 keys if their hex length is not 64 characters (32 bytes) lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php64-65
2. Compatibility: If phpseclib/mcrypt_compat is installed, Maho attempts to re-encrypt data using the legacy logic before switching to Sodium lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php68-69
3. Validation: Phase 1 of regeneration validates that all encrypted data can be decrypted with the current key before making any changes lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php95-116

Sources:

• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php64-80
• lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php95-116