Review main Merged

91439[FEATURE] Introduce symmetric encryption service via XChaCha20-Poly1305

Oliver Hader CR +2 V +2 Hard +744 −1 updated 11/19/25, 14:30

Commit message

This commit introduces a new CipherService API for symmetric encryption
and decryption of sensitive data. The service provides a secure,
standardized way for TYPO3 core and extensions to encrypt data such as
API tokens, passwords, or personal information.

Key aspects:
- uses modern XChaCha20-Poly1305 AEAD (Authenticated Encryption with
  Associated Data) cipher via libsodium
- provides encryption integrity verification to prevent tampering
- supports key derivation from existing TYPO3 encryption key, allowing
  application-specific isolated keys without additional key management
- supports optional additional authenticated data for context binding

Implementation:
- adds CipherService for encrypt/decrypt operations
- adds CipherValue for serializable encrypted data representation
- adds KeyFactory for deriving keys from master encryption key
- adds ext-sodium as new required PHP extension

Review

  • Code review CR +2 Done
    • Oliver Hader +2
    • Garvin Hicking +1
    • Markus Klein +1
  • Verified V +2 Done
    • Oliver Hader +2
    • Garvin Hicking +1
    • Markus Klein +1
    • core-ci +1 CI

Issues 1

Files 11

Review log 4054

Show 2029 earlier messages
  1. Oliver Hader uploaded patch set 1 11/06/25, 18:31

  2. core-ci voted on patch set 1 V +1 11/06/25, 18:39 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/88598

  3. Oliver Hader commented on patch set 1 11/06/25, 19:21

    KeyValueFactory.php:30

    Alternatively, `hash_hkdf` might be used
  4. Oliver Hader uploaded patch set 2 V +1 11/06/25, 22:17

  5. core-ci voted on patch set 2 V +1 11/06/25, 22:26 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/88606

  6. Oliver Hader uploaded patch set 3 V +1 11/07/25, 09:31

  7. Oliver Hader uploaded patch set 4 11/07/25, 09:38

  8. core-ci voted on patch set 3 V +1 11/07/25, 09:39 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/88634

  9. core-ci voted on patch set 4 V +1 11/07/25, 09:46 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/88635

  10. Oliver Hader uploaded patch set 5 V +1 11/11/25, 21:28

  11. Oliver Hader commented on patch set 5 11/11/25, 21:31

    This change is ready for review.
  12. Oliver Hader commented on patch set 5 11/11/25, 21:31

    KeyValueFactory.php:30 Reply

    Done
  13. core-ci voted on patch set 5 V -1 11/11/25, 21:36 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89079

  14. Oliver Hader uploaded patch set 6 V -1 11/11/25, 21:40

  15. core-ci voted on patch set 6 V +1 11/11/25, 21:49 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89083

  16. Garvin Hicking commented on patch set 6 11/11/25, 23:15

    KeyFactory.php:31

    We could remove the `@return` to prevent redundancy in type declarations

    Important-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:26

    ```suggestion the libsodium library (`ext-sodium`), which is available by default in all PHP versions currently supported by TYPO3. ```

    Important-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:42

    ```suggestion the same master key. Please note that to decrypt data in the future, the encryptionKey must not be changed, and must be kept available. ``` Something like that? Because I know some instances that rotate the encryption key from time to time. Up until now we only used the encryptionKey (to me knowledge) for temporary hash creation, and not persistive. And we have no description of this key in place. Even worse: https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-sys-encryptionkey basically says "its ok to change this, just flash your caches". So we definitely need to adapt main documentation to be suitable for this. I do think it's okay to make the encrpytionKey more important!
  17. Benni Mack commented on patch set 6 11/12/25, 08:47

    CipherService.php:46

    I suggest to use a "CipherDecryptionFailedException"
  18. Oliver Hader marked it work in progress 11/12/25, 09:15

  19. Oliver Hader updated the commit message in patch set 7 V +1 11/12/25, 09:16

  20. core-ci voted on patch set 7 V +1 11/12/25, 09:25 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89186

  21. Oliver Hader uploaded patch set 8 V +1 11/12/25, 17:31

  22. Oliver Hader commented on patch set 8 11/12/25, 17:31

    This change is ready for review.

    CipherService.php:46 Reply

    Done

    KeyFactory.php:31 Reply

    Done

    Important-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:26 Reply

    Done

    Important-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:42 Reply

    Done
  23. core-ci voted on patch set 8 V -1 11/12/25, 17:38 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89382

  24. Oliver Hader commented on patch set 9 V -1 11/12/25, 18:53

    Published edit on patch set 8.
  25. core-ci voted on patch set 9 V +1 11/12/25, 19:01 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89388

  26. Garvin Hicking commented on patch set 9 CR +1 11/12/25, 21:54

    nice!
  27. Christian Kuhn commented on patch set 9 11/13/25, 00:13

    KeyFactory.php:22

    obsolete since the class has no __construct().
  28. Oliver Hader marked it work in progress 11/13/25, 08:42

  29. Garvin Hicking commented on patch set 9 CR 0 V -1 11/13/25, 13:03

    I just tried this out with: ``` $secretKey = $this->keyFactory->deriveSharedKeyFromEncryptionKey('api-tokens'); echo "Encoding with: " . $secretKey->value . "\n"; $cipherValue = $this->cipherService->encrypt('4711', $secretKey); echo "Encrypted: " . $cipherValue . "\n"; ``` This fails on my PHP 8.2 setup because json_encode() does not seem to be able to handle the binary data. The `json_encode()` in `CipherValue->encode()` then resolves to a boolean `false` which is not passable. The JSON error message is: ``` Malformed UTF-8 characters, possibly incorrectly encoded ``` We probably could wrap a base64encode around cipher+nonce before passing it to json, and later on base64decode it, wdyt?

    SharedKey.php:26

    Are you intentionally not implementing a `__toString` method to provide access to $value, to not advertise "reading" the shared key easily?

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:61

    ```suggestion $secretKey = $this->keyFactory->deriveSharedKeyFromEncryptionKey('my-extension-tokens'); ``` (Also the ones below, was refactored in some patchset)

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:98

    ```suggestion $secretKey = $this->keyFactory->deriveSharedKeyFromEncryptionKey('api-tokens'); ```

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:137

    ```suggestion $secretKey = $this->keyFactory->deriveSharedKeyFromEncryptionKey('api-tokens'); ```

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:146

    ```suggestion } catch (CipherDecryptionFailedException $e) { ``` (unless you want to catch the broader exception as best practice)
  1. Oliver Hader uploaded patch set 10 V +1 11/13/25, 20:54

  2. Oliver Hader commented on patch set 9 11/13/25, 20:55

    This change is ready for review.

    Reply

    I now used `mb_convert_encoding` for invalid UTF-8 sequences & added a corresponding test for malformed byte sequences.

    KeyFactory.php:22 Reply

    Done

    SharedKey.php:26 Reply

    Yepp.

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:61 Reply

    Done

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:98 Reply

    Done

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:137 Reply

    Done

    Feature-108002-IntroduceBuilt-inSymmetricEncryptiondecryptionCipherService.rst:146 Reply

    Done
  3. Oliver Hader marked it ready for review 11/13/25, 20:55

  4. core-ci voted on patch set 10 V -1 11/13/25, 21:02 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89590

  5. Lina Wolf commented on patch set 10 11/13/25, 21:19

    CipherValue.php:54

    ```suggestion throw new CipherException('Failed to encode cipher value', 1763068727); ``` Needs a unique Exception code
  6. Oliver Hader commented on patch set 11 V -1 11/13/25, 21:30

    Published edit on patch set 10.
  7. core-ci voted on patch set 11 V +1 11/13/25, 21:40 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89595

  8. Oliver Hader commented on patch set 11 11/13/25, 22:24

    CipherValue.php:54 Reply

    Fix applied.
  9. Garvin Hicking commented on patch set 11 V -1 11/14/25, 18:53

    Reply

    Running the code above now yields: ``` Encoding with: �Y��U�X48g"u�PG(���^�P)ᜒ�\� Encrypted: eyJub25jZSI6Ilx1MDAwMyk_ez9gP1x1MDU4Nj8_XHUwNjdlP0RcdTAwMTM_XHUwMDAySVx1MDAxYzg_JyIsImNpcGhlciI6Ilx1MDAwZVx1MDAxM2M_c1x1MDAxNVx1MDAwMT9cdWM2M2U_P2AvPz8lPz8ifQ In CipherValue.php line 36: Incorrect nonce byte length ```
  10. Markus Klein commented on patch set 11 11/16/25, 21:09

    Reply

    I suppose the problem is the strlen-check in the constructor of `CipherValue` Since https://www.php.net/manual/en/function.random-bytes.php says > As the returned bytes are selected completely randomly, the resulting string is likely to contain unprintable characters or invalid UTF-8 sequences.
  11. Oliver Hader uploaded patch set 12 V +1 11/17/25, 10:24

  12. Oliver Hader commented on patch set 11 11/17/25, 10:24

    Reply

    That's why `strlen` is used instead of e.g. `mb_strlen` since the bytes shall be counted not the (UTF-8) chars. I'm dropping `mb_convert_encoding` in favor if using an additional Base64-layer.
  13. Markus Klein commented on patch set 12 11/17/25, 10:28

    Reply

    My thought was whether `strlen` fails on this byte-sequence too (for whatever reason).
  14. core-ci voted on patch set 12 V +1 11/17/25, 10:31 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89930

  15. Markus Klein uploaded patch set 13 V +1 11/18/25, 12:07

  16. core-ci voted on patch set 13 V +1 11/18/25, 12:17 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/90018

  17. Markus Klein voted on patch set 13 CR +1 V +1 11/18/25, 12:19

  18. Oliver Hader uploaded patch set 14 CR +1 V +1 11/19/25, 08:29

  19. core-ci voted on patch set 14 V +1 11/19/25, 08:36 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/90105

  20. Markus Klein voted on patch set 14 CR +1 V +1 11/19/25, 09:08

  21. Garvin Hicking commented on patch set 14 CR +1 V +1 11/19/25, 09:28

    This works now, thanks! @oliver.hader@typo3.org - how would you feel for a convenience method to shorten this: ``` $secretKey = $this->keyFactory->deriveSharedKeyFromEncryptionKey('api-tokens'); $cipherValue = CipherValue::fromSerialized('eyJub25jZSI6IktvUkFxbkNMaktoT0Y2a1c5Y04zdklUeFpvd0NhLWhwIiwiY2lwaGVyIjoiN2NxazlaQjZXRDVoOV9PaWVmbFV1UlFLQndVIn0'); $decrypted = $this->cipherService->decrypt($cipherValue, $secretKey); ``` to do this*: ``` $decrypted = $this->cipherService->decryptFromSerialized( 'eyJub25jZSI6IktvUkFxbkNMaktoT0Y2a1c5Y04zdklUeFpvd0NhLWhwIiwiY2lwaGVyIjoiN2NxazlaQjZXRDVoOV9PaWVmbFV1UlFLQndVIn0', 'api-tokens'); ``` A same convenience method could maybe be added for encrypt, let the cipherservice to the key derivation from an argument...? I understand if you feel this is too much "magic" then, so I'm voting also on the current implementation already.
  22. Oliver Hader commented on patch set 14 11/19/25, 14:10

    Reply

    Having a shortcut-method totally makes sense. I think it can be integrated in a separate patch.
  23. Garvin Hicking commented on patch set 14 11/19/25, 14:25

    Reply

    Fine by me, resolving this :)
  24. Oliver Hader voted on patch set 14 CR +2 V +2 11/19/25, 14:30

  25. Oliver Hader merged patch set 15 11/19/25, 14:30