Discussion: Encryption with Libsodium

The original Design Document is at HLD Removing mcrypt and adding libsodium.

Purpose of this page is to provide transparency via an open discussion. The page may include:

• open questions
• ideas and proposals
• notes and action items from the meetings

The page will be updated as the discussion progresses. See revisions of the page if needed.

---

To Investigate

1. What functions should we use: crypto_aead_* or crypto_secretbox*? See - recommendations (includes code sample)
   1. Also, clarify what ciphers are used to understand what needs to be added to the ciphertext
      1. XChaCha20-Poly1305-IETF (check what's supported by current library version) for crypto_aead_xchacha20poly1305_ietf or xsalsa20poly1305 for crypto_secretbox
2. Decide on migration strategy
   1. Calculate possible amount of stored encrypted data
3. Investigate if it's safe to use https://github.com/paragonie/sodium_compat
   1. It supports functions mentioned above
4. Based on the #3 decide on the implementation strategy:
   1. Completely switch to sodium (if sodium_compat is an acceptable option)
   2. Support both mcrypt and sodium based on what's installed in the system. Use mcrypt_compat for mcrypt support as we don't have mcrypt in composer.json requirements
5. Use mcrypt for decrypting existing data. Use mcrypt_compat. The \Magento\Framework\Encryption\Crypt::encrypt() in Magento Framework should be deprecated

Tasks

1. Deprecate \Magento\Framework\Encryption\Crypt. Its interface is incompatible with Sodium interface, so can't be reused. It can be still used for decrypting of old data. mcrypt_compat is already included in Magento 2.3, so nothing needs to be done in the class itself
   1. Potentially we won't be able to remove the library for long time (ever?) because merchants may migrate from old versions of Magento at any time in the future, and so it may be necessary to decrypt old data at any time. As an option (if it's necessary to remove the library for security compliance), we may remove it from the Magento Framework and release as a separate package with recommendations to use it for migration. In this case it should be distributed as a tool that migrates data, so that Magento code doesn't have references to the library.
2. Create EncryptorAdapterInterface
   1. Create SodiumAdapter implementation
   2. No necessity to create an mcrypt implementation as it will be deprecated anyways, it should not be an alternative for EncryptorAdapterInterface. Use existing \Magento\Framework\Encryption\Crypt instead (the only use case is to decrypt old messages
3. In \Magento\Framework\Encryption\Encryptor
   1. Add new version of cipher: based on the investigation
   2. In \Magento\Framework\Encryption\Encryptor::decrypt():
      1. Identify the library used for encryption based on the data
      2. Select the "strategy" (mcrypt vs sodium). As the mcrypt implementation does not really implement the EncryptorAdapterInterface interface, it won't be a real strategy, just different classes will be used based on the cipher.
      3. Decrypt
   3. In \Magento\Framework\Encryption\Encryptor::encrypt()
      1. Use sodium adapter
4. Update migration tool

May 4th Call

• First step: encryption only. Hashing can be done as a separate step later. To confirm with Piotr (Olga)
• Use crypto_aead_xchacha20poly1305_ietf*
• Data migration:
  1. Support "on-demand" approach. Current pattern in decryption supports this, we should follow it.
  2. Migrate on upgrade step. Investigate upgrade performance implications. Run test on different amount of data.
• https://github.com/paragonie/sodium_compat - follow-up on whether we can use this (Steven)
  1. Use sodium_compat for development now. Change later if necessary
• https://github.com/phpseclib/mcrypt_compat - follow-up on whether we can use this (Steven)
• Check performance with new implementation, both with native Sodium and sodium_compat one. Create a task (Olga)