vdm-io · pull · Oct 5, 2021 · Oct 5, 2021 · Oct 5, 2021 · Oct 5, 2021
diff --git a/.coveralls.yml b/.coveralls.yml
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,11 @@
+* text=auto
+
+/.github        export-ignore
+/doc            export-ignore
+/test          export-ignore
+/.coveralls.yml export-ignore
+/.gitattributes export-ignore
+/.gitignore     export-ignore
+/phpstan*       export-ignore
+/phpunit*       export-ignore
+/psalm*         export-ignore
diff --git a/.github/output/.gitkeep b/.github/output/.gitkeep
diff --git a/.github/output/README.md b/.github/output/README.md
@@ -0,0 +1,3 @@
+# Coverage Output
+
+If you are looking at the `image-data` branch, please know that this is just a hack to get the coverage badge working.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,67 +1,38 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
 
 jobs:
-  old:
+  phpunit:
     name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
     runs-on: ${{ matrix.operating-system }}
+    if: "!contains(github.event.head_commit.message, '[ci]')"
     strategy:
       matrix:
         operating-system: ['ubuntu-latest']
-        php-versions: ['7.2', '7.3']
-        phpunit-versions: ['latest']
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php-versions }}
-          extensions: mbstring, intl, sodium
-          ini-values: post_max_size=256M, max_execution_time=180
-          tools: psalm, phpunit:${{ matrix.phpunit-versions }}
-
-      - name: Install dependencies
-        run: composer install
+        php-versions: ['8.1', '8.2', '8.3', '8.4', '8.5']
 
-      - name: PHPUnit tests
-        uses: php-actions/phpunit@v2
-        timeout-minutes: 30
-        with:
-          memory_limit: 256M
-      - name: Static Analysis
-        run: vendor/bin/psalm
-
-  modern:
-    name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
-    runs-on: ${{ matrix.operating-system }}
-    strategy:
-      matrix:
-        operating-system: ['ubuntu-latest']
-        php-versions: ['7.4', '8.0']
-        phpunit-versions: ['latest']
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-versions }}
           extensions: mbstring, intl, sodium
-          ini-values: post_max_size=256M, max_execution_time=180
-          tools: psalm, phpunit:${{ matrix.phpunit-versions }}
+          ini-values: error_reporting=-1, display_errors=On
+          coverage: none
 
-      - name: Install dependencies
-        run: composer install
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
 
       - name: PHPUnit tests
-        uses: php-actions/phpunit@v2
-        timeout-minutes: 30
-        with:
-          memory_limit: 256M
+        run: vendor/bin/phpunit
 
-      - name: Static Analysis
-        run: vendor/bin/psalm
+      - name: PHPStan analysis
+        run: vendor/bin/phpstan
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -0,0 +1,56 @@
+name: Coverage
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  coverage:
+    name: PHP ${{ matrix.php-versions }} on ${{ matrix.operating-system }}
+    runs-on: ${{ matrix.operating-system }}
+    if: "!contains(github.event.head_commit.message, '[ci]')"
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.4']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: mbstring, intl, sodium, xdebug
+          ini-values: error_reporting=-1, display_errors=On
+          coverage: xdebug
+
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
+
+      - name: Ensure XML file is being loaded
+        run: cp phpunit.xml.dist phpunit.xml
+
+      - name: PHPUnit tests with coverage
+        run: vendor/bin/phpunit --coverage-clover clover.xml --coverage-html build/coverage-report
+
+      - name: phpunit-coverage-badge
+        uses: timkrase/phpunit-coverage-badge@v1.2.1
+        with:
+          coverage_badge_path: .github/output/coverage.svg
+          push_badge: false
+
+      - name: Git push to image-data branch
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_dir: .github/output
+          publish_branch: image-data
+          github_token: ${{ secrets.TOKEN }}
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
diff --git a/.github/workflows/psalm.yml b/.github/workflows/psalm.yml
@@ -0,0 +1,32 @@
+name: Psalm
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  psalm:
+    name: Psalm on PHP ${{ matrix.php-versions }}
+    runs-on: ${{ matrix.operating-system }}
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.1', '8.2', '8.3', '8.4', '8.5']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          coverage: none
+
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
+
+      - name: Psalm static analysis
+        run: vendor/bin/psalm
diff --git a/.gitignore b/.gitignore
@@ -14,3 +14,5 @@
 /composer.lock
 /composer.phar
 /.idea/
+/.phpunit.result.cache
+/phpstan.neon
diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,59 @@
 # Changelog
 
+## Version 5.1.4 (2025-09-18)
+
+* Add PHPStan analysis, level 5 by @spaze in https://github.com/paragonie/halite/pull/195
+* Replace all `http://` links with the `https://` URL they redirect to by @GrahamCampbell in https://github.com/paragonie/halite/pull/196
+* Use Psalm 6 by @spaze in https://github.com/paragonie/halite/pull/198
+* Remove access modifier `final` from private methods by @junaidbinfarooq in https://github.com/paragonie/halite/pull/204
+* Ignore tests, workflows and .MD docs with "export-ignore" on .gitattr… by @erikn69 in https://github.com/paragonie/halite/pull/205
+* Expand test coverage by @paragonie-security in https://github.com/paragonie/halite/pull/206
+* Fixed the broken test coverage badge (https://github.com/paragonie/halite/pull/207 and https://github.com/paragonie/halite/pull/208)
+
+## Version 5.1.3 (2025-01-23)
+
+* Merged [#184](https://github.com/paragonie/halite/pull/194), which fixes PHP 8.4 deprecations with nullable types.
+
+## Version 5.1.2 (2024-05-08)
+
+* Use `#[SensitiveParameter]` annotation on some inputs
+  * This is defense in depth; we already wrapped most in `HiddenString`
+* Updated dependencies
+
+## Version 5.1.1 (2024-04-19)
+
+* Support both sodium_compat v1 and v2. 
+  [Learn more here](https://paragonie.com/blog/2024/04/release-sodium-compat-v2-and-future-our-polyfill-libraries).
+
+## Version 5.1.0 (2022-05-23)
+
+* Dropped PHP 8.0 support, increased minimum PHP version to 8.1.
+  * This is due to the significant performance difference between ext/sodium
+    and sodium_compat, and the functions we use in 5.x aren't available until
+    PHP 8.1. See [#178](https://github.com/paragonie/halite/issues/178).
+* The 5.0.x branch will continue to *function* on PHP 8.0 but performance is
+  not guaranteed.
+
+## Version 5.0.0 (2022-01-19)
+
+* Increased minimum PHP version to 8.0.
+* **Security:** Asymmetric encryption now uses HKDF-BLAKE2b to extract a 256-bit uniformly random bit string for the
+  encryption key, rather than using the raw X25519 output directly as an encryption key. This is important because 
+  Elliptic Curve Diffie-Hellman results in a random group element, but that isn't necessarily a uniformly random bit
+  string.
+  * Because Halite v4 and earlier did not perform this step, it's superficially susceptible to
+    [Cheon's attack](https://crypto.stackexchange.com/a/67609). This reduces the effective security
+    from 125 bits (Pollard's rho) to 123 bits, but neither is a practical concern today.
+* **Security:** Halite v5 uses the [PAE](https://github.com/paseto-standard/paseto-spec/blob/master/docs/01-Protocol-Versions/Common.md#pae-definition)
+  strategy from PASETO to prevent canonicalization attacks.
+* **Security:** Halite v5 appends the random salt to HKDF's `info` parameter instead of
+  the `salt` parameter. This allows us to meet the KDF Security Definition (which is
+  stronger than a mere Pseudo-Random Function).
+* Encryption now uses XChaCha20 instead of XSalsa20.
+* The `File` class no longer supports the `resource` type. To migrate code, wrap your 
+  `resource` arguments in a `ReadOnlyFile` or `MutableFile` object.
+* Added `File::asymmetricEncrypt()` and `File::asymmetricDecrypt()`.
+
 ## Version 4.8.0 (2021-04-18)
 
 * Merged [#158](https://github.com/paragonie/halite/pull/158), which removes

diff --git a/LICENSE b/LICENSE
@@ -357,7 +357,7 @@ Exhibit A - Source Code Form License Notice
 
   This Source Code Form is subject to the terms of the Mozilla Public
   License, v. 2.0. If a copy of the MPL was not distributed with this
-  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+  file, You can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.
 
 If it is not possible or desirable to put the notice in a particular
 file, then You may include the notice in a location (such as a LICENSE

diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
 # Halite
 
 [![Build Status](https://github.com/paragonie/halite/actions/workflows/ci.yml/badge.svg)](https://github.com/paragonie/halite/actions)
+[![Static Analysis](https://github.com/paragonie/halite/actions/workflows/psalm.yml/badge.svg)](https://github.com/paragonie/halite/actions)
 [![Latest Stable Version](https://poser.pugx.org/paragonie/halite/v/stable)](https://packagist.org/packages/paragonie/halite)
 [![Latest Unstable Version](https://poser.pugx.org/paragonie/halite/v/unstable)](https://packagist.org/packages/paragonie/halite)
 [![License](https://poser.pugx.org/paragonie/halite/license)](https://packagist.org/packages/paragonie/halite)
 [![Downloads](https://img.shields.io/packagist/dt/paragonie/halite.svg)](https://packagist.org/packages/paragonie/halite)
-[![Coverage Status](https://coveralls.io/repos/github/paragonie/halite/badge.svg?branch=master)](https://coveralls.io/github/paragonie/halite?branch=master)
+[![Coverage Status](https://raw.githubusercontent.com/paragonie/halite/refs/heads/image-data/coverage.svg)](https://github.com/paragonie/halite/actions/workflows/coverage.yml)
 
 **Halite** is a high-level cryptography interface that relies on [libsodium](https://pecl.php.net/package/libsodium)
 for all of its underlying cryptography operations.
@@ -34,15 +35,19 @@ Before you can use Halite, you must choose a version that fits the requirements
 of your project. The differences between the requirements for the available 
 versions of Halite are briefly highlighted below.
 
-|                                                             | PHP   | libsodium | PECL libsodium | Support                   |
-|-------------------------------------------------------------|-------|-----------|----------------|---------------------------|
-| Halite 4.1 and newer                                        | 7.2.0 | 1.0.15    | N/A (standard) | :heavy_check_mark: Active |
-| [Halite 4.0](https://github.com/paragonie/halite/tree/v4.0) | 7.2.0 | 1.0.13    | N/A (standard) | :heavy_check_mark: Active |
-| [Halite 3](https://github.com/paragonie/halite/tree/v3.x)   | 7.0.0 | 1.0.9     | 1.0.6 / 2.0.4  | :x: Not Supported         |
-| [Halite 2](https://github.com/paragonie/halite/tree/v2.2)   | 7.0.0 | 1.0.9     | 1.0.6          | :x: Not Supported         |
-| [Halite 1](https://github.com/paragonie/halite/tree/v1.x)   | 5.6.0 | 1.0.6     | 1.0.2          | :x: Not Supported         |
+|                                                              | PHP   | libsodium | PECL libsodium | Support                   |
+|--------------------------------------------------------------|-------|-----------|----------------|---------------------------|
+| Halite 5.1 and newer                                         | 8.1.0 | 1.0.18    | N/A (standard) | :heavy_check_mark: Active |
+| Halite 5.0.x                                                 | 8.0.0 | 1.0.18    | N/A (standard) | :heavy_check_mark: Active |
+| [Halite 4.1+](https://github.com/paragonie/halite/tree/v4.x) | 7.2.0 | 1.0.15    | N/A (standard) | :x: Not Supported         |
+| [Halite 4.0](https://github.com/paragonie/halite/tree/v4.0)  | 7.2.0 | 1.0.13    | N/A (standard) | :x: Not Supported         |
+| [Halite 3](https://github.com/paragonie/halite/tree/v3.x)    | 7.0.0 | 1.0.9     | 1.0.6 / 2.0.4  | :x: Not Supported         |
+| [Halite 2](https://github.com/paragonie/halite/tree/v2.2)    | 7.0.0 | 1.0.9     | 1.0.6          | :x: Not Supported         |
+| [Halite 1](https://github.com/paragonie/halite/tree/v1.x)    | 5.6.0 | 1.0.6     | 1.0.2          | :x: Not Supported         |
 
-If you need a version of Halite before 4.0, see the documentation relevant to that
+Note: Halite 5.0.x works on PHP 8.0, but performance is worse than on PHP 8.1.
+
+If you need a version of Halite before 5.1, see the documentation relevant to that
 particular branch.
 
 **To install Halite, you first need to [install libsodium](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium).**
@@ -56,11 +61,11 @@ If you're stuck, [this step-by-step guide contributed by @aolko](doc/Install-Gui
 
 Once you have the prerequisites installed, install Halite through [Composer](https://getcomposer.org/doc/00-intro.md):
 
-    composer require paragonie/halite:^4
+    composer require paragonie/halite:^5
 
 ### Commercial Support for Older Halite Versions
 
-Free (gratis) support for Halite only extends to the most recent major version (currently 4).
+Free (gratis) support for Halite only extends to the most recent major version (currently 5).
 
 If your company requires support for an older version of Halite,
 [contact Paragon Initiative Enterprises](https://paragonie.com/contact) to inquire about
@@ -75,14 +80,18 @@ Check out the [documentation](doc). The basic Halite API is designed for simplic
   * Encryption
     * Symmetric
        * `Symmetric\Crypto::encrypt`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md)): `string`
+       * `Symmetric\Crypto::encryptWithAD`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md), `string`): `string`
        * `Symmetric\Crypto::decrypt`(`string`, [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
+       * `Symmetric\Crypto::decryptWithAD`(`string`, [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md), `string`): [`HiddenString`](doc/Classes/HiddenString.md)
     * Asymmetric
        * Anonymous
          * `Asymmetric\Crypto::seal`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): `string`
          * `Asymmetric\Crypto::unseal`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
        * Authenticated
          * `Asymmetric\Crypto::encrypt`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): `string`
+         * `Asymmetric\Crypto::encryptWithAD`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md), `string`): `string`
          * `Asymmetric\Crypto::decrypt`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
+         * `Asymmetric\Crypto::decryptWithAD`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md), `string`): [`HiddenString`](doc/Classes/HiddenString.md)
   * Authentication
     * Symmetric
        * `Symmetric\Crypto::authenticate`(`string`, [`AuthenticationKey`](doc/Classes/Symmetric/AuthenticationKey.md)): `string`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Coverage Output

		If you are looking at the `image-data` branch, please know that this is just a hack to get the coverage badge working.