You are browsing the documentation for iTop 3.0 which is not the current version.

Consider browsing to iTop 3.1 documentation

Encrypted data

  • As of PHP 7.2, the mcrypt library that iTop was using to encrypt AttributeEncryptedString, was removed from PHP core.
  • iTop versions before 2.6.0 are only able to encrypt through mcrypt, thus AttributeEncryptedString for these versions, is not compatible with PHP >= 7.2.
  • iTop user accounts passwords use a one-way encryption (AttributeOneWayPassword) and are not affected by the presence or absence of mcrypt.
iTop 2.6 supports other PHP encryption library and retro-compatibility for data already encrypted with mcrypt in previous versions.

Configuration

Two configuration parameters controls the iTop data encryption logic:

Parameter Type Visible ? Description Default Value
encryption_library string Yes Library amongst: Sodium, OpenSSL, OpenSSLMcryptCompatibility, Simple Sodium
encryption_key string Yes An encryption key is generated once and entered here. @iT0pEncr1pti0n!

In order to pick an encryption library you'll need to define encryption_library in the configuration file, this parameter can take for value : Sodium, OpenSSL, OpenSSLMcryptCompatibility or Simple.

  • The chosen library needs to be installed and enabled in the current PHP installation (see setup/phpinfo.php).
  • You will also be required to define the key encryption_key that is used for iTop symetrical encryption (make sure you never loose it!). The method to generate the key is specific to each library, check below for details.
If encryption_library and/or encryption_key are not defined, iTop will choose a library depending on your PHP installation and generate a key if Sodium or OpenSSL library were chosen

Sodium

LibSodium is a cryptography library shipped with PHP core as of PHP 7.2.

The current usage of Sodium in iTop encrypt data with Salsa20 stream cipher using the PHP (> 7.0) built in function random_bytes to generate a salt and saves data as base64 values.

LibSodium needs a SODIUM_CRYPTO_SECRETBOX_KEYBYTES bytes long encryption key. In order to ease admin to generate this key, we save it as an hexadecimal value.

Example to generate a valid Sodium key :

 php -r "echo bin2hex(sodium_crypto_secretbox_keygen());" > itop_secret_key.txt 

OpenSSL

OpenSSL is a cryptography library frequently shipped with PHP.

The current usage of OpenSSL in iTop encrypt data with AES-256-CBC block cipher using openssl pseudo random bytes function to generate an initialisation vector.

This implementation of OpenSSL automaticaly pads the encryption key with zeros and saves data as base64 values.

For security reasons OpenSSL needs a 256 bits long encryption key. In order to ease admin to generate this key, we save it as an hexadecimal value.

Example to generate a valid AES-256 key :

 php -r "echo bin2hex(openssl_random_pseudo_bytes(32));" > itop_secret_key.txt 
Until PHP 5.6.12 open_ssl_random_pseudo_bytes() is not a cryptographically secure pseudo-random number generator. As we use it for initialisation vector creation, we recommand you to update your PHP installation to >= 5.6.12.

OpenSSLMcryptCompatibility

We DO NOT recommand using Mcrypt as it is an abandonware and was dropped from PHP core for obvious security reasons. However, if you already have mcrypt encrypted data, you can use OpenSSLMcryptCompatibility library option which allows you to still work on these data.

Mcrypt is a (deprecated) cryptography library that used to be shipped with PHP core up to PHP 7.1.

The current usage of Mcrypt in iTop encrypt data with BLOWFISH-CBC block cipher using mcrypt (or openssl) pseudo random bytes function to generate an initialisation vector.

If Mcrypt is specified but the library not installed (eg. in PHP 7.2+), iTop will try to use its backup OpenSSLMcryptCompatibility using OpenSSL library.

Simple

Simple is a weaker algortihm that encrypt with no salt. It's used by iTop if the library specified in encryption_library isn't installed or enabled in PHP.

Questions & Answers

Q: How can I migrate an existing iTop from one encryption library to another? A: This is tricky and requires direct access to the iTop database.

  • 1. Do a CSV or Excel export of all iTop objects which do have AttributeEncryptedString. (There is no such classes in iTop default datamodel)
  • 2. Upgrade/migrate your iTop (ensure the future PHP encryption library is available) then run a Setup
  • 3. Change the Configuration File parameters
After step 3, the objects with encrypted field are no more readable and creation can be a pain
  • 4. Create manually using the 3.0 top left plus icon, a dummy object for each class having an AttributeEncryptedString, and feed the password value

  • 5. Connect to the iTop database and for each dummy object, retrieve the encrypted value of the password (<encrypted-password-value>) in the object table
SELECT <password-sql-code> FROM <my-object-table> WHERE id=<my-id>;
  • 6. Set that valid value (<encrypted-password-value>) on all objects of that table
UPDATE <my-object-table> SET <password-sql-code> = <encrypted-password-value>;
  • 7. Import by CSV to previously exported real data, to restore the real password values
  • 8. Delete the dummy objects
3_0_0/feature/encrypt_data.txt ยท Last modified: 2022/09/16 10:51 (external edit)
Back to top
Contact us