Add modern cryptors by olegbaturin · Pull Request #71 · yiisoft/security

olegbaturin · 2026-05-16T11:38:08Z

Q	A
Is bugfix?	❌
New feature?	✔️
Breaks BC?	❌

add tests

codecov · 2026-05-16T11:40:04Z

Codecov Report

❌ Patch coverage is 96.59091% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.84%. Comparing base (a0bbbe3) to head (2ad87b1).

Files with missing lines	Patch %	Lines
src/Crypt/Cipher/OpenSSLAeadCipher.php	91.17%	3 Missing ⚠️
src/Crypt/Cipher/SodiumAeadCipher.php	94.11%	2 Missing ⚠️
src/Crypt/Kdf/KdfPasswordArgon2.php	91.66%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##              master      #71      +/-   ##
=============================================
- Coverage     100.00%   97.84%   -2.16%     
- Complexity        37      101      +64     
=============================================
  Files              7       15       +8     
  Lines            102      278     +176     
=============================================
+ Hits             102      272     +170     
- Misses             0        6       +6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR introduces a new “modern” AEAD-based encryption layer to the package (new cipher/KDF abstractions plus high-level cryptors), along with documentation, CI updates, and a small PasswordHasher adjustment.

Changes:

Added AEAD cipher interfaces and implementations for OpenSSL (AES-GCM) and libsodium (AES-256-GCM/ChaCha20-Poly1305/XChaCha20-Poly1305).
Added KDF abstractions/implementations (HKDF-based key derivation, plus PBKDF2+HKDF for passwords) and high-level cryptors (Session, Envelope, Versioned).
Added PHPUnit coverage for new cryptors/ciphers/KDFs and updated README/CI/Composer metadata accordingly.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`src/Crypt/CipherInterface.php`	Introduces base cipher abstraction used by new cryptors.
`src/Crypt/AeadCipherInterface.php`	Adds AEAD-specific cipher contract (tag size).
`src/Crypt/Cipher/OpenSSLAeadCipher.php`	OpenSSL-backed AES-GCM AEAD cipher implementation.
`src/Crypt/Cipher/SodiumAeadCipher.php`	libsodium-backed AEAD cipher implementation (AES-GCM/ChaCha variants).
`src/Crypt/KdfInterface.php`	Introduces key-derivation abstraction used by cryptors.
`src/Crypt/Kdf/KdfKey.php`	HKDF-based KDF for high-entropy secrets.
`src/Crypt/Kdf/KdfPassword.php`	PBKDF2+HKDF-based KDF for passwords.
`src/Crypt/CryptorInterface.php`	Defines high-level encrypt/decrypt contract for new cryptors.
`src/Crypt/SessionCryptor.php`	Implements per-message derived-key “session” encryption format.
`src/Crypt/EnvelopeCryptor.php`	Implements envelope encryption (wrapped DEK) format.
`src/Crypt/VersionedCryptor.php`	Adds version-prefix wrapper to support cryptor migrations.
`src/Crypt/EncryptionException.php`	Introduces a dedicated exception type for encryption/decryption failures.
`tests/Crypt/AbstractAeadCipherCase.php`	Shared test suite for AEAD cipher implementations.
`tests/Crypt/OpenSSLAeadCipherTest.php`	OpenSSL AEAD cipher tests.
`tests/Crypt/SodiumAeadCipherTest.php`	libsodium ChaCha/XChaCha AEAD cipher tests.
`tests/Crypt/SodiumGcmCipherTest.php`	libsodium AES-256-GCM AEAD cipher tests (hardware dependent).
`tests/Crypt/AbstractKdfCase.php`	Shared test suite for KDF implementations.
`tests/Crypt/KdfKeyTest.php`	HKDF KDF tests.
`tests/Crypt/KdfPasswordTest.php`	PBKDF2+HKDF KDF tests.
`tests/Crypt/SessionCryptorTest.php`	Session cryptor unit tests.
`tests/Crypt/EnvelopeCryptorTest.php`	Envelope cryptor unit tests.
`tests/Crypt/VersionedCryptorTest.php`	Versioned cryptor unit tests.
`README.md`	Documents the new cryptors/KDFs/ciphers and marks legacy cryptor as “old”.
`composer.json`	Adds `ext-sodium` requirement.
`.github/workflows/build.yml`	Enables sodium extension in CI.
`psalm.xml`	Adjusts Psalm configuration.
`CHANGELOG.md`	Notes the new cryptors in the unreleased version section.
`src/PasswordHasher.php`	Adjusts SAFE_PARAMETERS lookup when algorithm is `null`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    "require": {
        "php": "8.1 - 8.5",
        "ext-hash": "*",
        "ext-openssl": "*",
+        "ext-sodium": "*",
        "yiisoft/strings": "^2.0"


+`Crypt` provides encryption layer based on `AEAD` algorithms.
+It supports key derivation, session‑oriented encryption, envelope encryption, and versioned ciphertexts for seamless algorithm migration.


add argon2 kdf

samdark

Not enough negative/security tests around metadata tampering: version byte changes, salt/nonce field mutation, truncated payloads at every boundary, truncated tags, empty plaintext, wrong context, and cross-version/cross-cryptor confusion.

samdark · 2026-05-26T15:19:33Z

+        $tag = StringHelper::byteSubstring($data, -self::TAG_SIZE);
+        $ciphertext = StringHelper::byteSubstring($data, 0, -self::TAG_SIZE);
+
+        $decrypted = openssl_decrypt($ciphertext, $this->cipher, $key, OPENSSL_RAW_DATA | OPENSSL_DONT_ZERO_PAD_KEY, $nonce, $tag);


Truncated GCM tags issue. If $data is shorter than TAG_SIZE, we pass a 1-15 byte tag to openssl_decrypt(), and OpenSSL authenticates only the supplied tag bytes. That makes empty-plaintext forgery possible. One can search, for example, a 1-byte tag succeeds in about 256 attempts. Reject $data shorter than self::TAG_SIZE before slicing, and add tests for empty plaintext plus truncated tags.

samdark · 2026-05-26T15:19:51Z

        "php": "8.1 - 8.5",
        "ext-hash": "*",
        "ext-openssl": "*",
+        "ext-sodium": "*",


Move to suggests.

samdark · 2026-05-26T15:22:10Z

+     * @throws RuntimeException If sodium extension is missing, cipher not allowed, or AES-256-GCM without hardware support.
+     */
+    public function __construct(
+        private readonly string $cipher = 'AES-256-GCM',


Is it a good default since there could be no hardware support? In the README, the cipher is not configured, so the following examples will result in an exception.

How about choosing default such as XChaCha20-Poly1305-IETF?

samdark · 2026-05-26T15:22:47Z

+
+```php
+// /config/di.php
+use Yiisoft\Security\Crypt\Kdf\KdfPassword;


KdfPasswordPbkdf2 / KdfPasswordArgon2?

samdark · 2026-05-26T15:22:59Z

+
+KdfPassword::class => [
+    '__construct()' => [
+        'algorithm' => 'sha512', // any hash_hmac_algos()


hashAlgo?

samdark · 2026-05-26T15:27:00Z

+    ): string {
+        $payload = $this->cryptors[$this->currentVersion]->encrypt($data, $secret, $context);
+
+        return $this->currentVersion . $payload;


Metadata is not being authenticated. Shouldn't it?

samdark · 2026-05-26T15:28:06Z

+        $dataEncrypted = $this->cipher->encrypt($data, $dek, $dataNonce);
+
+        // keySalt || dekNonce || cipherdek || tag || dataNonce || ciphertext || tag
+        return $keySalt . $dekNonce . $dekEncrypted . $dataNonce . $dataEncrypted;


Metadata is not authenticated. Shouldn't it?

samdark · 2026-05-26T15:34:37Z

+        string $salt,
+    ): string {
+        try {
+            $key = sodium_crypto_pwhash($keySize, $secret, $salt, $this->opslimit, $this->memlimit, $this->algo);


Suggested change

$key = sodium_crypto_pwhash($keySize, $secret, $salt, $this->opslimit, $this->memlimit, $this->algo);

$key = sodium_crypto_pwhash(32, $secret, $salt, $this->opslimit, $this->memlimit, $this->algo);

This size should not depend on algo.

samdark · 2026-05-26T15:35:14Z

+        string $salt,
+    ): string {
+        try {
+            $key = hash_pbkdf2($this->hashAlgo, $secret, $salt, $this->iterations, $keySize, true);


Suggested change

$key = hash_pbkdf2($this->hashAlgo, $secret, $salt, $this->iterations, $keySize, true);

$key = hash_pbkdf2($this->hashAlgo, $secret, $salt, $this->iterations, 32, true);

This size should not depend on algo.

olegbaturin added 17 commits May 11, 2026 17:33

add cryptor

917f747

fix style

6156063

add readonly

c5bd2ac

update doc

90205a7

add kdf doc

be74463

add doc to the cryptors

1e2dbd0

replace mb_substr with StringHelper

395e497

replace mb_strlen

74ab9ee

update config

ab88999

fix config

e3d033e

update envelope cryptor

f3371b9

add tests

add copher tests

024ab0f

add kdf tests

a9b2fed

fix psalm

e3b42cc

add versioned test

1ada6d7

remove config

e30b789

update changelog

c31e2e2

olegbaturin added 12 commits May 16, 2026 18:48

fix style

14c6555

fix style

5a261fc

fix style

7469377

fix style

b53adc4

fix psalm

dd005ec

update tests

ef21a64

update composer.json

b2cb9da

update ci

ac79a08

update ci

bf24623

update ci

8b64a32

update phpdoc

1001c88

update readme

2750e71

add OPENSSL_DONT_ZERO_PAD_KEY to gcp cipher

d574ca8

vjik reviewed May 23, 2026

View reviewed changes

Comment thread src/PasswordHasher.php

samdark requested a review from Copilot May 23, 2026 15:13

Copilot started reviewing on behalf of samdark May 23, 2026 15:13 View session

Copilot AI reviewed May 23, 2026

View reviewed changes

olegbaturin and others added 9 commits May 24, 2026 02:31

fix copilot suggestions

2dee4ae

fix style

bad4df8

update phpdoc

d49ad96

add saltSize to kdf interface

c7b0247

add argon2 kdf

fix psalm

7e29630

update phpdoc

b638977

fix misprint

4043010

update psalm for ciphers without nounce

2345581

Merge branch 'master' into add-cryptor

2ad87b1

samdark requested changes May 26, 2026

View reviewed changes

		`Crypt` provides encryption layer based on `AEAD` algorithms.
		It supports key derivation, session‑oriented encryption, envelope encryption, and versioned ciphertexts for seamless algorithm migration.

	$key = sodium_crypto_pwhash($keySize, $secret, $salt, $this->opslimit, $this->memlimit, $this->algo);
	$key = sodium_crypto_pwhash(32, $secret, $salt, $this->opslimit, $this->memlimit, $this->algo);

	$key = hash_pbkdf2($this->hashAlgo, $secret, $salt, $this->iterations, $keySize, true);
	$key = hash_pbkdf2($this->hashAlgo, $secret, $salt, $this->iterations, 32, true);

Uh oh!

Conversation

olegbaturin commented May 16, 2026

Uh oh!

codecov Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samdark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov Bot commented May 16, 2026 •

edited

Loading